@diamondslab/diamonds-hardhat-foundry 2.3.0 → 2.4.0

package/src/framework/ForgeCoverageFramework.ts

@@ -1,37 +1,138 @@
 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 - Orchestrates forge coverage execution for Diamond contracts
+ * ForgeCoverageFramework - Main orchestration class for Forge coverage with Diamonds
  *
- * Responsibilities:
- * 1. Build forge coverage command with all options
- * 2. Execute forge coverage with proper fork URL
- * 3. Stream output to terminal
- * 4. Handle errors appropriately
+ * 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 {
-  constructor(private hre: HardhatRuntimeEnvironment) {}
+  private deploymentManager: DeploymentManager;
+  private helperGenerator: HelperGenerator;
+
+  constructor(private hre: HardhatRuntimeEnvironment) {
+    this.deploymentManager = new DeploymentManager(hre);
+    this.helperGenerator = new HelperGenerator(hre);
+  }
 
   /**
-   * Run forge coverage with provided options
+   * 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, false otherwise
+   * @returns Promise<boolean> - true if coverage succeeds
    */
   async runCoverage(options: CoverageOptions = {}): Promise<boolean> {
-    Logger.section("Forge Coverage - Execution");
+    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 {
-      // Build command arguments
-      const args = this.buildCoverageCommand(options);
+      // 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)...\n");
+      Logger.info("⏳ Running coverage analysis (this may take a while)...");
 
-      // Execute forge coverage
       const success = await this.executeForge(args);
 
       if (success) {
@@ -42,7 +143,7 @@ export class ForgeCoverageFramework {
 
       return success;
     } catch (error: any) {
-      Logger.error(`Coverage execution error: ${error.message}`);
+      Logger.error(`Coverage execution failed: ${error.message}`);
       return false;
     }
   }
@@ -80,9 +181,9 @@ export class ForgeCoverageFramework {
 
     // Multiple --report flags
     if (options.report && options.report.length > 0) {
-      options.report.forEach((reportType) => {
+      for (const reportType of options.report) {
         args.push("--report", reportType);
-      });
+      }
     }
 
     if (options.reportFile) {
@@ -266,12 +367,13 @@ export class ForgeCoverageFramework {
    */
   private executeForge(args: string[]): Promise<boolean> {
     return new Promise((resolve, reject) => {
-      const forgeProcess = spawn("forge", ["coverage", ...args], {
+      const forge = spawn("forge", ["coverage", ...args], {
         cwd: this.hre.config.paths.root,
-        stdio: "inherit", // Stream output directly to terminal
+        stdio: "inherit",
+        shell: true,
       });
 
-      forgeProcess.on("close", (code) => {
+      forge.on("close", (code) => {
         if (code === 0) {
           resolve(true);
         } else {
@@ -279,8 +381,9 @@ export class ForgeCoverageFramework {
         }
       });
 
-      forgeProcess.on("error", (error) => {
-        reject(new Error(`Failed to execute forge coverage: ${error.message}`));
+      forge.on("error", (error) => {
+        Logger.error(`Failed to execute forge: ${error.message}`);
+        reject(error);
       });
     });
   }

package/src/tasks/coverage.ts

@@ -11,18 +11,20 @@ import { Logger } from "../utils/logger";
  * - 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")
-  .addParam(
+  .addOptionalParam(
     "diamondName",
     "Name of the Diamond to analyze",
-    undefined,
+    "ExampleDiamond",
     types.string
   )
   // Report options
   .addOptionalParam(
     "report",
-    "Report type (summary, lcov, debug, bytecode) - can be used multiple times by passing comma-separated values",
+    "Report type (summary, lcov, debug, bytecode) - comma-separated for multiple",
     undefined,
     types.string
   )
@@ -34,7 +36,7 @@ task("diamonds-forge:coverage", "Run forge coverage for Diamond contracts")
   )
   .addOptionalParam(
     "lcovVersion",
-    "LCOV format version",
+    "LCOV format version (v1 or v2)",
     undefined,
     types.string
   )
@@ -44,50 +46,50 @@ task("diamonds-forge:coverage", "Run forge coverage for Diamond contracts")
   // Test filtering
   .addOptionalParam(
     "matchTest",
-    "Run tests matching pattern (--match-test)",
+    "Run tests matching pattern",
     undefined,
     types.string
   )
   .addOptionalParam(
     "noMatchTest",
-    "Exclude tests matching pattern (--no-match-test)",
+    "Exclude tests matching pattern",
     undefined,
     types.string
   )
   .addOptionalParam(
     "matchContract",
-    "Run contracts matching pattern (--match-contract)",
+    "Run contracts matching pattern",
     undefined,
     types.string
   )
   .addOptionalParam(
     "noMatchContract",
-    "Exclude contracts matching pattern (--no-match-contract)",
+    "Exclude contracts matching pattern",
     undefined,
     types.string
   )
   .addOptionalParam(
     "matchPath",
-    "Run files matching glob (--match-path)",
+    "Run files matching glob",
     undefined,
     types.string
   )
   .addOptionalParam(
     "noMatchPath",
-    "Exclude files matching glob (--no-match-path)",
+    "Exclude files matching glob",
     undefined,
     types.string
   )
   .addOptionalParam(
     "noMatchCoverage",
-    "Exclude files from coverage report (--no-match-coverage)",
+    "Exclude files from coverage report",
     undefined,
     types.string
   )
   // Display options
   .addOptionalParam(
     "verbosity",
-    "Verbosity level (1-5, more v's = more verbose)",
+    "Verbosity level (1-5)",
     undefined,
     types.int
   )
@@ -141,7 +143,7 @@ task("diamonds-forge:coverage", "Run forge coverage for Diamond contracts")
     types.string
   )
   .addFlag("ffi", "Enable FFI cheatcode")
-  // Build options
+  // Build/deployment options
   .addFlag("force", "Force recompile and redeploy")
   .addFlag("noCache", "Disable cache")
   .addFlag("optimize", "Enable Solidity optimizer")
@@ -152,151 +154,100 @@ task("diamonds-forge:coverage", "Run forge coverage for Diamond contracts")
     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;
 
-    // Validate required parameters
-    if (!diamondName) {
-      Logger.error("--diamond-name is required");
-      process.exitCode = 1;
-      return;
-    }
-
     Logger.info(`Diamond: ${diamondName}`);
     Logger.info(`Network: ${networkName}`);
 
-    try {
-      // Lazy-load framework classes to avoid circular dependency
-      const { DeploymentManager } = await import("../framework/DeploymentManager.js");
-      const { HelperGenerator } = await import("../framework/HelperGenerator.js");
-
-      // Step 1: Ensure Diamond deployment
-      Logger.section("Step 1/3: Ensuring Diamond Deployment");
-      
-      const deploymentManager = new DeploymentManager(hre);
-      
-      await deploymentManager.ensureDeployment(
-        diamondName,
-        networkName,
-        taskArgs.force || false,
-        false // Don't write deployment data for coverage (ephemeral by default)
-      );
-
-      // Step 2: Generate helpers
-      Logger.section("Step 2/3: Generating Solidity Helpers");
-      
-      const deployment = await deploymentManager.getDeployment(
-        diamondName,
-        networkName
-      );
-
-      if (!deployment) {
-        Logger.error("No deployment found. Cannot generate helpers.");
-        process.exitCode = 1;
-        return;
-      }
-
-      const provider = hre.ethers.provider;
-      const network = await provider.getNetwork();
-      const chainId = Number(network.chainId);
-      const deploymentData = deployment.getDeployedDiamondData();
-
-      const helperGenerator = new HelperGenerator(hre);
-      await helperGenerator.generateDeploymentHelpers(
-        diamondName,
-        networkName,
-        chainId,
-        deploymentData,
-        deployment
-      );
-
-      // Step 3: Run coverage
-      Logger.section("Step 3/3: Running Forge Coverage");
-
-      // Construct fork URL for network
-      // Coverage requires forking from a running network to access deployed contracts
-      let forkUrl: string;
-      if (networkName !== "hardhat") {
-        // Use the configured network's URL
-        forkUrl = (provider as any)._hardhatProvider?._wrapped?.url || "http://127.0.0.1:8545";
-        Logger.info(`Forking from ${networkName}: ${forkUrl}`);
-      } else {
-        // Default to localhost for hardhat network
-        // This assumes user has `npx hardhat node` running
-        forkUrl = "http://127.0.0.1:8545";
-        Logger.warn(`⚠️  Network is "${networkName}" - defaulting to localhost fork: ${forkUrl}`);
-        Logger.warn(`💡 Make sure Hardhat node is running: npx hardhat node`);
-        Logger.warn(`💡 Or specify network explicitly: --network localhost`);
-      }
+    // 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
-      const { ForgeCoverageFramework } = await import("../framework/ForgeCoverageFramework.js");
-      type CoverageOptions = Parameters<InstanceType<typeof ForgeCoverageFramework>["runCoverage"]>[0];
+    // 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];
 
-      // Build coverage options from task args
-      const options: CoverageOptions = {
-        // Fork URL
-        forkUrl,
+    // Parse comma-separated report types
+    const reportTypes = taskArgs.report
+      ? taskArgs.report.split(",").map((r: string) => r.trim())
+      : undefined;
 
-        // Report options
-        report: taskArgs.report ? taskArgs.report.split(",") : undefined,
-        reportFile: taskArgs.reportFile,
-        lcovVersion: taskArgs.lcovVersion,
-        includeLibs: taskArgs.includeLibs,
-        excludeTests: taskArgs.excludeTests,
-        irMinimum: taskArgs.irMinimum,
+    // 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,
+    };
 
-        // Test filtering
-        matchTest: taskArgs.matchTest,
-        noMatchTest: taskArgs.noMatchTest,
-        matchContract: taskArgs.matchContract,
-        noMatchContract: taskArgs.noMatchContract,
-        matchPath: taskArgs.matchPath,
-        noMatchPath: taskArgs.noMatchPath,
-        noMatchCoverage: taskArgs.noMatchCoverage,
+    // Run coverage using the framework (same pattern as test.ts)
+    const framework = new ForgeCoverageFramework(hre);
 
-        // Display options
-        verbosity: taskArgs.verbosity,
-        quiet: taskArgs.quiet,
-        json: taskArgs.json,
-        md: taskArgs.md,
-        color: taskArgs.color as "auto" | "always" | "never" | undefined,
-
-        // Test execution options
-        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
-        force: taskArgs.force,
-        noCache: taskArgs.noCache,
-        optimize: taskArgs.optimize,
-        optimizerRuns: taskArgs.optimizerRuns,
-        viaIr: taskArgs.viaIr,
-      };
-
-      // Run coverage
-      const framework = new ForgeCoverageFramework(hre);
+    try {
       const success = await framework.runCoverage(options);
 
       if (success) {
         Logger.section("Coverage Analysis Complete");
-        Logger.success("Coverage analysis completed successfully!");
+        Logger.success("✅ Coverage completed successfully!");
         process.exitCode = 0;
       } else {
         Logger.section("Coverage Analysis Complete");
-        Logger.error("Coverage analysis failed");
+        Logger.error("❌ Coverage analysis failed");
         process.exitCode = 1;
       }
     } catch (error: any) {

package/src/types/config.ts

@@ -66,8 +66,21 @@ export type ColorMode = "auto" | "always" | "never";
 /**
  * Coverage options for forge coverage command
  * Maps to all available forge coverage command-line options
+ * Plus orchestration options for Diamond deployment and helpers
  */
 export interface CoverageOptions {
+  // Orchestration options (matching ForgeFuzzingFramework pattern)
+  /** Name of the Diamond to analyze */
+  diamondName?: string;
+  /** Network name for deployment (hardhat, localhost, etc.) */
+  networkName?: string;
+  /** Skip Diamond deployment step */
+  skipDeployment?: boolean;
+  /** Skip helper generation step */
+  skipHelpers?: boolean;
+  /** Write deployment data to file for reuse */
+  writeDeployedDiamondData?: boolean;
+
   // Report options
   /** Report type(s) - can specify multiple */
   report?: CoverageReportType[];