@diamondslab/diamonds-hardhat-foundry 2.2.3 → 2.4.0

package/src/framework/ForgeCoverageFramework.ts

@@ -0,0 +1,390 @@
+import { spawn } from "child_process";
+import { HardhatRuntimeEnvironment } from "hardhat/types";
+import { CoverageOptions } from "../types/config";
+import { isFoundryInstalled } from "../utils/foundry";
+import { Logger } from "../utils/logger";
+import { DeploymentManager } from "./DeploymentManager";
+import { HelperGenerator } from "./HelperGenerator";
+
+/**
+ * ForgeCoverageFramework - Main orchestration class for Forge coverage with Diamonds
+ *
+ * Coordinates:
+ * 1. Diamond deployment via DeploymentManager
+ * 2. Helper generation via HelperGenerator
+ * 3. Forge coverage execution
+ *
+ * Mirrors ForgeFuzzingFramework design for consistency and code reuse
+ */
+export class ForgeCoverageFramework {
+  private deploymentManager: DeploymentManager;
+  private helperGenerator: HelperGenerator;
+
+  constructor(private hre: HardhatRuntimeEnvironment) {
+    this.deploymentManager = new DeploymentManager(hre);
+    this.helperGenerator = new HelperGenerator(hre);
+  }
+
+  /**
+   * Run complete Forge coverage workflow
+   *
+   * Workflow:
+   * 1. Validate Foundry installation
+   * 2. Deploy or reuse Diamond
+   * 3. Generate Solidity helpers
+   * 4. Run forge coverage with options
+   *
+   * @param options - Coverage execution options
+   * @returns Promise<boolean> - true if coverage succeeds
+   */
+  async runCoverage(options: CoverageOptions = {}): Promise<boolean> {
+    const {
+      diamondName = "ExampleDiamond",
+      networkName = "hardhat",
+      force = false,
+      skipDeployment = false,
+      skipHelpers = false,
+      writeDeployedDiamondData = false,
+    } = options;
+
+    Logger.section("Running Forge Coverage with Diamond");
+
+    // Step 1: Validate Foundry
+    if (!isFoundryInstalled()) {
+      Logger.error(
+        "Foundry is not installed. Please install it: https://book.getfoundry.sh/getting-started/installation"
+      );
+      return false;
+    }
+
+    try {
+      // Step 2: Ensure Diamond deployment
+      if (!skipDeployment) {
+        Logger.section("Step 1/3: Ensuring Diamond Deployment");
+        await this.deploymentManager.ensureDeployment(
+          diamondName,
+          networkName,
+          force,
+          writeDeployedDiamondData
+        );
+      } else {
+        Logger.info("Skipping deployment (using existing)");
+      }
+
+      // Step 3: Generate helpers
+      if (!skipHelpers) {
+        Logger.section("Step 2/3: Generating Solidity Helpers");
+
+        const deployment = await this.deploymentManager.getDeployment(
+          diamondName,
+          networkName
+        );
+
+        if (!deployment) {
+          Logger.warn("⚠ No deployment record found");
+          if (!skipDeployment) {
+            Logger.info("ℹ Using cached deployment (ephemeral)");
+          }
+        } else {
+          Logger.info("Using deployment record");
+        }
+
+        const provider = this.hre.ethers.provider;
+        const network = await provider.getNetwork();
+        const chainId = Number(network.chainId);
+
+        const deploymentData = deployment
+          ? deployment.getDeployedDiamondData()
+          : await this.deploymentManager
+              .ensureDeployment(diamondName, networkName, false, false)
+              .then((d) => d.getDeployedDiamondData());
+
+        await this.helperGenerator.generateDeploymentHelpers(
+          diamondName,
+          networkName,
+          chainId,
+          deploymentData,
+          deployment || undefined
+        );
+      } else {
+        Logger.info("Skipping helper generation");
+      }
+
+      // Step 4: Run coverage
+      Logger.section("Step 3/3: Running Forge Coverage");
+
+      // Get fork URL for network (same pattern as ForgeFuzzingFramework)
+      const provider = this.hre.ethers.provider;
+      let forkUrl: string;
+
+      if (networkName !== "hardhat") {
+        forkUrl = (provider as any).connection?.url || "http://127.0.0.1:8545";
+      } else {
+        forkUrl = "http://127.0.0.1:8545";
+        Logger.warn(
+          "⚠️  Network is \"hardhat\" - defaulting to localhost fork: http://127.0.0.1:8545"
+        );
+        Logger.warn("💡 Make sure Hardhat node is running: npx hardhat node");
+        Logger.warn("💡 Or specify network explicitly: --network localhost");
+      }
+
+      const args = this.buildCoverageCommand({ ...options, forkUrl });
+
+      Logger.info(`Executing: forge coverage ${args.join(" ")}`);
+      Logger.info("⏳ Running coverage analysis (this may take a while)...");
+
+      const success = await this.executeForge(args);
+
+      if (success) {
+        Logger.success("✅ Coverage analysis completed successfully");
+      } else {
+        Logger.error("❌ Coverage analysis failed");
+      }
+
+      return success;
+    } catch (error: any) {
+      Logger.error(`Coverage execution failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Build complete forge coverage command arguments
+   *
+   * @param options - Coverage options
+   * @returns Array of command arguments
+   */
+  private buildCoverageCommand(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    // Add fork URL if provided
+    if (options.forkUrl) {
+      args.push("--fork-url", options.forkUrl);
+    }
+
+    // Add all option groups
+    args.push(...this.buildReportOptions(options));
+    args.push(...this.buildFilterOptions(options));
+    args.push(...this.buildDisplayOptions(options));
+    args.push(...this.buildTestOptions(options));
+    args.push(...this.buildEvmOptions(options));
+    args.push(...this.buildBuildOptions(options));
+
+    return args.filter((arg) => arg !== "");
+  }
+
+  /**
+   * Build report-related options
+   */
+  private buildReportOptions(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    // Multiple --report flags
+    if (options.report && options.report.length > 0) {
+      for (const reportType of options.report) {
+        args.push("--report", reportType);
+      }
+    }
+
+    if (options.reportFile) {
+      args.push("--report-file", options.reportFile);
+    }
+
+    if (options.lcovVersion) {
+      args.push("--lcov-version", options.lcovVersion);
+    }
+
+    if (options.includeLibs) {
+      args.push("--include-libs");
+    }
+
+    if (options.excludeTests) {
+      args.push("--exclude-tests");
+    }
+
+    if (options.irMinimum) {
+      args.push("--ir-minimum");
+    }
+
+    return args;
+  }
+
+  /**
+   * Build test filtering options
+   */
+  private buildFilterOptions(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    if (options.matchTest) {
+      args.push("--match-test", options.matchTest);
+    }
+
+    if (options.noMatchTest) {
+      args.push("--no-match-test", options.noMatchTest);
+    }
+
+    if (options.matchContract) {
+      args.push("--match-contract", options.matchContract);
+    }
+
+    if (options.noMatchContract) {
+      args.push("--no-match-contract", options.noMatchContract);
+    }
+
+    if (options.matchPath) {
+      args.push("--match-path", options.matchPath);
+    }
+
+    if (options.noMatchPath) {
+      args.push("--no-match-path", options.noMatchPath);
+    }
+
+    if (options.noMatchCoverage) {
+      args.push("--no-match-coverage", options.noMatchCoverage);
+    }
+
+    return args;
+  }
+
+  /**
+   * Build display options
+   */
+  private buildDisplayOptions(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    // Verbosity (-v, -vv, -vvv, etc.)
+    if (options.verbosity && options.verbosity > 0) {
+      args.push("-" + "v".repeat(options.verbosity));
+    }
+
+    if (options.quiet) {
+      args.push("--quiet");
+    }
+
+    if (options.json) {
+      args.push("--json");
+    }
+
+    if (options.md) {
+      args.push("--md");
+    }
+
+    if (options.color) {
+      args.push("--color", options.color);
+    }
+
+    return args;
+  }
+
+  /**
+   * Build test execution options
+   */
+  private buildTestOptions(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    if (options.threads !== undefined) {
+      args.push("--threads", options.threads.toString());
+    }
+
+    if (options.fuzzRuns !== undefined) {
+      args.push("--fuzz-runs", options.fuzzRuns.toString());
+    }
+
+    if (options.fuzzSeed) {
+      args.push("--fuzz-seed", options.fuzzSeed);
+    }
+
+    if (options.failFast) {
+      args.push("--fail-fast");
+    }
+
+    if (options.allowFailure) {
+      args.push("--allow-failure");
+    }
+
+    return args;
+  }
+
+  /**
+   * Build EVM options
+   */
+  private buildEvmOptions(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    if (options.forkBlockNumber !== undefined) {
+      args.push("--fork-block-number", options.forkBlockNumber.toString());
+    }
+
+    if (options.initialBalance) {
+      args.push("--initial-balance", options.initialBalance);
+    }
+
+    if (options.sender) {
+      args.push("--sender", options.sender);
+    }
+
+    if (options.ffi) {
+      args.push("--ffi");
+    }
+
+    return args;
+  }
+
+  /**
+   * Build build options
+   */
+  private buildBuildOptions(options: CoverageOptions): string[] {
+    const args: string[] = [];
+
+    if (options.force) {
+      args.push("--force");
+    }
+
+    if (options.noCache) {
+      args.push("--no-cache");
+    }
+
+    if (options.optimize) {
+      args.push("--optimize");
+    }
+
+    if (options.optimizerRuns !== undefined) {
+      args.push("--optimizer-runs", options.optimizerRuns.toString());
+    }
+
+    if (options.viaIr) {
+      args.push("--via-ir");
+    }
+
+    return args;
+  }
+
+  /**
+   * Execute forge coverage command and stream output
+   *
+   * @param args - Command arguments
+   * @returns Promise<boolean> - true if command succeeds
+   */
+  private executeForge(args: string[]): Promise<boolean> {
+    return new Promise((resolve, reject) => {
+      const forge = spawn("forge", ["coverage", ...args], {
+        cwd: this.hre.config.paths.root,
+        stdio: "inherit",
+        shell: true,
+      });
+
+      forge.on("close", (code) => {
+        if (code === 0) {
+          resolve(true);
+        } else {
+          resolve(false);
+        }
+      });
+
+      forge.on("error", (error) => {
+        Logger.error(`Failed to execute forge: ${error.message}`);
+        reject(error);
+      });
+    });
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 import { extendConfig, extendEnvironment, internalTask, task } from "hardhat/config";
+import "./tasks/coverage";
 import "./tasks/deploy";
 import "./tasks/generate-helpers";
 import "./tasks/init";
@@ -7,17 +8,17 @@ import "./types/hardhat";
 
 import { existsSync, writeFileSync } from "fs";
 import {
-  TASK_COMPILE_GET_REMAPPINGS,
-  TASK_COMPILE_TRANSFORM_IMPORT_NAME,
+    TASK_COMPILE_GET_REMAPPINGS,
+    TASK_COMPILE_TRANSFORM_IMPORT_NAME,
 } from "hardhat/builtin-tasks/task-names";
 import { HardhatRuntimeEnvironment } from "hardhat/types";
 import path from "path";
 import picocolors from "picocolors";
 import {
-  getForgeConfig,
-  getRemappings,
-  HardhatFoundryError,
-  installDependency,
+    getForgeConfig,
+    getRemappings,
+    HardhatFoundryError,
+    installDependency,
 } from "./foundry";
 import { validateConfig } from "./utils/validation";
 

package/src/tasks/coverage.ts

@@ -0,0 +1,258 @@
+import { task, types } from "hardhat/config";
+import { HardhatRuntimeEnvironment } from "hardhat/types";
+import { Logger } from "../utils/logger";
+
+/**
+ * Task: diamonds-forge:coverage
+ *
+ * Runs Forge coverage with Diamond deployment.
+ * - Ensures Diamond deployment exists
+ * - Generates Solidity helpers
+ * - Runs forge coverage with specified options
+ *
+ * Use Hardhat's built-in --network flag to specify the network
+ * 
+ * Design: Mirrors diamonds-forge:test task structure for consistency
+ */
+task("diamonds-forge:coverage", "Run forge coverage for Diamond contracts")
+  .addOptionalParam(
+    "diamondName",
+    "Name of the Diamond to analyze",
+    "ExampleDiamond",
+    types.string
+  )
+  // Report options
+  .addOptionalParam(
+    "report",
+    "Report type (summary, lcov, debug, bytecode) - comma-separated for multiple",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "reportFile",
+    "Output path for report file",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "lcovVersion",
+    "LCOV format version (v1 or v2)",
+    undefined,
+    types.string
+  )
+  .addFlag("includeLibs", "Include libraries in coverage report")
+  .addFlag("excludeTests", "Exclude tests from coverage report")
+  .addFlag("irMinimum", "Enable viaIR with minimum optimization")
+  // Test filtering
+  .addOptionalParam(
+    "matchTest",
+    "Run tests matching pattern",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "noMatchTest",
+    "Exclude tests matching pattern",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "matchContract",
+    "Run contracts matching pattern",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "noMatchContract",
+    "Exclude contracts matching pattern",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "matchPath",
+    "Run files matching glob",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "noMatchPath",
+    "Exclude files matching glob",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "noMatchCoverage",
+    "Exclude files from coverage report",
+    undefined,
+    types.string
+  )
+  // Display options
+  .addOptionalParam(
+    "verbosity",
+    "Verbosity level (1-5)",
+    undefined,
+    types.int
+  )
+  .addFlag("quiet", "Suppress log output")
+  .addFlag("json", "Format output as JSON")
+  .addFlag("md", "Format output as Markdown")
+  .addOptionalParam(
+    "color",
+    "Color mode (auto, always, never)",
+    undefined,
+    types.string
+  )
+  // Test execution options
+  .addOptionalParam(
+    "threads",
+    "Number of threads to use",
+    undefined,
+    types.int
+  )
+  .addOptionalParam(
+    "fuzzRuns",
+    "Number of fuzz runs",
+    undefined,
+    types.int
+  )
+  .addOptionalParam(
+    "fuzzSeed",
+    "Seed for fuzz randomness",
+    undefined,
+    types.string
+  )
+  .addFlag("failFast", "Stop on first failure")
+  .addFlag("allowFailure", "Exit 0 even if tests fail")
+  // EVM options
+  .addOptionalParam(
+    "forkBlockNumber",
+    "Fork from specific block number",
+    undefined,
+    types.int
+  )
+  .addOptionalParam(
+    "initialBalance",
+    "Initial balance for test contracts",
+    undefined,
+    types.string
+  )
+  .addOptionalParam(
+    "sender",
+    "Test sender address",
+    undefined,
+    types.string
+  )
+  .addFlag("ffi", "Enable FFI cheatcode")
+  // Build/deployment options
+  .addFlag("force", "Force recompile and redeploy")
+  .addFlag("noCache", "Disable cache")
+  .addFlag("optimize", "Enable Solidity optimizer")
+  .addOptionalParam(
+    "optimizerRuns",
+    "Optimizer runs",
+    undefined,
+    types.int
+  )
+  .addFlag("viaIr", "Use Yul IR compilation")
+  .addFlag("skipDeployment", "Skip Diamond deployment step")
+  .addFlag("skipHelpers", "Skip helper generation step")
+  .addFlag("saveDeployment", "Write deployment data to file for reuse")
+  .setAction(async (taskArgs, hre: HardhatRuntimeEnvironment) => {
+    Logger.section("Running Forge Coverage with Diamond");
+
+    const diamondName = taskArgs.diamondName;
+    const networkName = hre.network.name;
+
+    Logger.info(`Diamond: ${diamondName}`);
+    Logger.info(`Network: ${networkName}`);
+
+    // Log key options
+    if (taskArgs.report) Logger.info(`Report: ${taskArgs.report}`);
+    if (taskArgs.reportFile) Logger.info(`Report File: ${taskArgs.reportFile}`);
+    if (taskArgs.matchTest) Logger.info(`Match Test: ${taskArgs.matchTest}`);
+    if (taskArgs.matchContract) Logger.info(`Match Contract: ${taskArgs.matchContract}`);
+    if (taskArgs.skipDeployment) Logger.info("Skip Deployment: true");
+    if (taskArgs.skipHelpers) Logger.info("Skip Helpers: true");
+    if (taskArgs.saveDeployment) Logger.info("Save Deployment: true");
+
+    // Lazy-load framework to avoid circular dependency during config loading
+    const { ForgeCoverageFramework } = await import(
+      "../framework/ForgeCoverageFramework.js"
+    );
+    type CoverageOptions = Parameters<
+      InstanceType<typeof ForgeCoverageFramework>["runCoverage"]
+    >[0];
+
+    // Parse comma-separated report types
+    const reportTypes = taskArgs.report
+      ? taskArgs.report.split(",").map((r: string) => r.trim())
+      : undefined;
+
+    // Create coverage options (matches test.ts pattern)
+    const options: CoverageOptions = {
+      diamondName,
+      networkName,
+      force: taskArgs.force,
+      skipDeployment: taskArgs.skipDeployment,
+      skipHelpers: taskArgs.skipHelpers,
+      writeDeployedDiamondData: taskArgs.saveDeployment,
+      // Report options
+      report: reportTypes,
+      reportFile: taskArgs.reportFile,
+      lcovVersion: taskArgs.lcovVersion,
+      includeLibs: taskArgs.includeLibs,
+      excludeTests: taskArgs.excludeTests,
+      irMinimum: taskArgs.irMinimum,
+      // Test filtering
+      matchTest: taskArgs.matchTest,
+      noMatchTest: taskArgs.noMatchTest,
+      matchContract: taskArgs.matchContract,
+      noMatchContract: taskArgs.noMatchContract,
+      matchPath: taskArgs.matchPath,
+      noMatchPath: taskArgs.noMatchPath,
+      noMatchCoverage: taskArgs.noMatchCoverage,
+      // Display options
+      verbosity: taskArgs.verbosity,
+      quiet: taskArgs.quiet,
+      json: taskArgs.json,
+      md: taskArgs.md,
+      color: taskArgs.color,
+      // Test execution
+      threads: taskArgs.threads,
+      fuzzRuns: taskArgs.fuzzRuns,
+      fuzzSeed: taskArgs.fuzzSeed,
+      failFast: taskArgs.failFast,
+      allowFailure: taskArgs.allowFailure,
+      // EVM options
+      forkBlockNumber: taskArgs.forkBlockNumber,
+      initialBalance: taskArgs.initialBalance,
+      sender: taskArgs.sender,
+      ffi: taskArgs.ffi,
+      // Build options
+      noCache: taskArgs.noCache,
+      optimize: taskArgs.optimize,
+      optimizerRuns: taskArgs.optimizerRuns,
+      viaIr: taskArgs.viaIr,
+    };
+
+    // Run coverage using the framework (same pattern as test.ts)
+    const framework = new ForgeCoverageFramework(hre);
+
+    try {
+      const success = await framework.runCoverage(options);
+
+      if (success) {
+        Logger.section("Coverage Analysis Complete");
+        Logger.success("✅ Coverage completed successfully!");
+        process.exitCode = 0;
+      } else {
+        Logger.section("Coverage Analysis Complete");
+        Logger.error("❌ Coverage analysis failed");
+        process.exitCode = 1;
+      }
+    } catch (error: any) {
+      Logger.error(`Coverage execution failed: ${error.message}`);
+      process.exitCode = 1;
+      throw error;
+    }
+  });