@diamondslab/diamonds-hardhat-foundry 1.0.0

package/src/framework/ForgeFuzzingFramework.ts

@@ -0,0 +1,194 @@
+import { HardhatRuntimeEnvironment } from "hardhat/types";
+import { compileForge, isFoundryInstalled, runForgeTest } from "../utils/foundry";
+import { Logger } from "../utils/logger";
+import { DeploymentManager } from "./DeploymentManager";
+import { HelperGenerator } from "./HelperGenerator";
+
+export interface ForgeTestOptions {
+  /** Name of the Diamond to deploy */
+  diamondName?: string;
+  /** Network to deploy on */
+  networkName?: string;
+  /** Force redeployment */
+  force?: boolean;
+  /** Match test pattern */
+  matchTest?: string;
+  /** Match contract pattern */
+  matchContract?: string;
+  /** Verbosity level (1-5) */
+  verbosity?: number;
+  /** Show gas report */
+  gasReport?: boolean;
+  /** Skip helper generation */
+  skipHelpers?: boolean;
+  /** Skip deployment (use existing) */
+  skipDeployment?: boolean;
+}
+
+/**
+ * ForgeFuzzingFramework - Main orchestration class for Forge testing with Diamonds
+ * 
+ * Coordinates:
+ * 1. Diamond deployment via DeploymentManager
+ * 2. Helper generation via HelperGenerator
+ * 3. Forge test execution
+ */
+export class ForgeFuzzingFramework {
+  private deploymentManager: DeploymentManager;
+  private helperGenerator: HelperGenerator;
+
+  constructor(private hre: HardhatRuntimeEnvironment) {
+    this.deploymentManager = new DeploymentManager(hre);
+    this.helperGenerator = new HelperGenerator(hre);
+  }
+
+  /**
+   * Run complete Forge testing workflow
+   * 
+   * Workflow:
+   * 1. Validate Foundry installation
+   * 2. Deploy or reuse Diamond
+   * 3. Generate Solidity helpers
+   * 4. Compile Forge contracts
+   * 5. Run Forge tests
+   * 
+   * @param options - Test execution options
+   */
+  async runTests(options: ForgeTestOptions = {}): Promise<boolean> {
+    const {
+      diamondName = "ExampleDiamond",
+      networkName = "hardhat",
+      force = false,
+      matchTest,
+      matchContract,
+      verbosity = 2,
+      gasReport = false,
+      skipHelpers = false,
+      skipDeployment = false,
+    } = options;
+
+    Logger.section("Forge Fuzzing Framework - Test Execution");
+
+    // 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/4: Ensuring Diamond Deployment");
+        await this.deploymentManager.ensureDeployment(
+          diamondName,
+          networkName,
+          force
+        );
+      } else {
+        Logger.info("Skipping deployment (using existing)");
+      }
+
+      // Step 3: Generate helpers
+      if (!skipHelpers) {
+        Logger.section("Step 2/4: Generating Solidity Helpers");
+        const deployment = await this.deploymentManager.getDeployment(
+          diamondName,
+          networkName
+        );
+
+        if (!deployment) {
+          Logger.error("No deployment found. Cannot generate helpers.");
+          return false;
+        }
+
+        const provider = this.hre.ethers.provider;
+        const network = await provider.getNetwork();
+        const chainId = Number(network.chainId);
+
+        const deploymentData = deployment.getDeployedDiamondData();
+        
+        await this.helperGenerator.generateDeploymentHelpers(
+          diamondName,
+          networkName,
+          chainId,
+          deploymentData
+        );
+      } else {
+        Logger.info("Skipping helper generation");
+      }
+
+      // Step 4: Compile Forge contracts
+      Logger.section("Step 3/4: Compiling Forge Contracts");
+      const compileResult = await compileForge({
+        cwd: this.hre.config.paths.root,
+        verbose: verbosity >= 3,
+      });
+
+      if (!compileResult.success) {
+        Logger.error("Forge compilation failed");
+        return false;
+      }
+
+      // Step 5: Run tests
+      Logger.section("Step 4/4: Running Forge Tests");
+      const testResult = await runForgeTest({
+        matchTest,
+        matchContract,
+        verbosity,
+        gasReport,
+        cwd: this.hre.config.paths.root,
+      });
+
+      return testResult.success;
+    } catch (error: any) {
+      Logger.error(`Test execution failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Deploy Diamond only (no testing)
+   */
+  async deployOnly(
+    diamondName: string = "ExampleDiamond",
+    networkName: string = "hardhat",
+    force: boolean = false
+  ) {
+    return await this.deploymentManager.ensureDeployment(
+      diamondName,
+      networkName,
+      force
+    );
+  }
+
+  /**
+   * Generate helpers only (no deployment or testing)
+   */
+  async generateHelpersOnly(
+    diamondName: string = "ExampleDiamond",
+    networkName: string = "hardhat"
+  ) {
+    const deployment = await this.deploymentManager.getDeployment(
+      diamondName,
+      networkName
+    );
+
+    if (!deployment) {
+      throw new Error("No deployment found. Deploy first using deployOnly()");
+    }
+
+    const provider = this.hre.ethers.provider;
+    const network = await provider.getNetwork();
+    const chainId = Number(network.chainId);
+
+    const deploymentData = deployment.getDeployedDiamondData();
+
+    return await this.helperGenerator.generateDeploymentHelpers(
+      diamondName,
+      networkName,
+      chainId,
+      deploymentData
+    );
+  }
+}
+

package/src/framework/HelperGenerator.ts

@@ -0,0 +1,246 @@
+import { DeployedDiamondData } from "@diamondslab/diamonds";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { HardhatRuntimeEnvironment } from "hardhat/types";
+import { join } from "path";
+import { Logger } from "../utils/logger";
+
+/**
+ * HelperGenerator - Generates Solidity helper files for testing
+ */
+export class HelperGenerator {
+  constructor(private hre: HardhatRuntimeEnvironment) {}
+
+  /**
+   * Scaffold project with initial test structure
+   */
+  async scaffoldProject(outputDir?: string): Promise<void> {
+    const helpersDir = outputDir || this.hre.diamondsFoundry.helpersDir;
+    const basePath = join(this.hre.config.paths.root, helpersDir);
+
+    Logger.section("Scaffolding Forge Test Structure");
+    
+    // Create directories
+    Logger.step("Creating directories...");
+    mkdirSync(basePath, { recursive: true });
+    mkdirSync(join(basePath, "../unit"), { recursive: true });
+    mkdirSync(join(basePath, "../integration"), { recursive: true });
+    mkdirSync(join(basePath, "../fuzz"), { recursive: true });
+
+    Logger.success(`Test structure created at ${basePath}`);
+  }
+
+  /**
+   * Generate DiamondDeployment.sol from deployment record
+   */
+  async generateDeploymentHelpers(
+    diamondName: string,
+    networkName: string,
+    chainId: number,
+    deploymentData: DeployedDiamondData
+  ): Promise<string> {
+    Logger.section("Generating Diamond Deployment Helper");
+
+    const helpersDir = this.hre.diamondsFoundry.helpersDir;
+    const outputPath = join(
+      this.hre.config.paths.root,
+      helpersDir,
+      "DiamondDeployment.sol"
+    );
+
+    const content = this.generateLibrarySource(
+      diamondName,
+      networkName,
+      chainId,
+      deploymentData
+    );
+
+    // Ensure directory exists
+    mkdirSync(join(this.hre.config.paths.root, helpersDir), {
+      recursive: true,
+    });
+
+    // Write file
+    writeFileSync(outputPath, content, "utf8");
+
+    Logger.success(`Generated: ${outputPath}`);
+    return outputPath;
+  }
+
+  /**
+   * Generate example test files
+   */
+  async generateExampleTests(): Promise<string[]> {
+    const generated: string[] = [];
+    const examples = this.hre.diamondsFoundry.exampleTests;
+
+    if (!this.hre.diamondsFoundry.generateExamples) {
+      Logger.info("Example generation disabled in config");
+      return generated;
+    }
+
+    Logger.section("Generating Example Tests");
+
+    const basePath = join(this.hre.config.paths.root, "test", "foundry");
+    const templatesPath = join(__dirname, "../templates");
+
+    for (const type of examples) {
+      let templateFile = "";
+      let outputPath = "";
+
+      switch (type) {
+        case "unit":
+          templateFile = join(templatesPath, "ExampleUnitTest.t.sol.template");
+          outputPath = join(basePath, "unit", "ExampleUnit.t.sol");
+          break;
+        case "integration":
+          templateFile = join(templatesPath, "ExampleIntegrationTest.t.sol.template");
+          outputPath = join(basePath, "integration", "ExampleIntegration.t.sol");
+          break;
+        case "fuzz":
+          templateFile = join(templatesPath, "ExampleFuzzTest.t.sol.template");
+          outputPath = join(basePath, "fuzz", "ExampleFuzz.t.sol");
+          break;
+        default:
+          Logger.warn(`Unknown example type: ${type}`);
+          continue;
+      }
+
+      try {
+        // Check if template exists
+        if (!existsSync(templateFile)) {
+          Logger.warn(`Template not found: ${templateFile}`);
+          continue;
+        }
+
+        // Read template content
+        const templateContent = readFileSync(templateFile, "utf8");
+
+        // Ensure output directory exists
+        mkdirSync(join(basePath, type), { recursive: true });
+
+        // Check if file already exists
+        if (existsSync(outputPath)) {
+          Logger.info(`Skipping ${type} example (already exists): ${outputPath}`);
+          continue;
+        }
+
+        // Write example test file
+        writeFileSync(outputPath, templateContent, "utf8");
+        Logger.success(`Generated ${type} example: ${outputPath}`);
+        generated.push(outputPath);
+      } catch (error: any) {
+        Logger.error(`Failed to generate ${type} example: ${error.message}`);
+      }
+    }
+
+    if (generated.length === 0) {
+      Logger.info("No new example tests generated (may already exist)");
+    }
+
+    return generated;
+  }
+
+  /**
+   * Generate Solidity library source from deployment data
+   * @private
+   */
+  private generateLibrarySource(
+    diamondName: string,
+    networkName: string,
+    chainId: number,
+    deploymentData: DeployedDiamondData
+  ): string {
+    const timestamp = new Date().toISOString();
+    const networkInfo = `${networkName}-${chainId}`;
+    const deploymentFileName = `${diamondName.toLowerCase()}-${networkInfo}.json`;
+    const deploymentFilePath = `diamonds/${diamondName}/deployments/${deploymentFileName}`;
+
+    let source = "";
+
+    // SPDX and pragma
+    source += "// SPDX-License-Identifier: MIT\n";
+    source += "pragma solidity ^0.8.19;\n\n";
+
+    // Header comments
+    source += "/**\n";
+    source += ` * @title DiamondDeployment\n`;
+    source += ` * @notice Auto-generated deployment data for ${diamondName}\n`;
+    source += ` * @dev This library provides constants and helper functions for accessing\n`;
+    source += ` *      deployment data in Forge tests. It is auto-generated from the deployment\n`;
+    source += ` *      record and should not be edited manually.\n`;
+    source += ` *\n`;
+    source += ` * Generated from: ${deploymentFilePath}\n`;
+    source += ` * Generated at: ${timestamp}\n`;
+    source += ` *\n`;
+    source += ` * To regenerate this file:\n`;
+    source += ` *   npx hardhat diamonds-forge:generate-helpers --diamond ${diamondName}\n`;
+    source += ` *\n`;
+    source += ` * ⚠️  DO NOT EDIT MANUALLY - Changes will be overwritten on next generation\n`;
+    source += " */\n";
+    source += "library DiamondDeployment {\n";
+
+    // Diamond address
+    source += `    /// @notice Address of the deployed ${diamondName} contract\n`;
+    source += `    /// @dev This is the main Diamond proxy address\n`;
+    source += `    address constant DIAMOND_ADDRESS = ${deploymentData.DiamondAddress};\n\n`;
+
+    // Facet addresses
+    source += "    // ========================================\n";
+    source += "    // Facet Addresses\n";
+    source += "    // ========================================\n\n";
+
+    const facets = deploymentData.DeployedFacets ?? {};
+    for (const [facetName, facetData] of Object.entries(facets)) {
+      const constantName = facetName
+        .replace(/Facet$/, "")
+        .replace(/([A-Z])/g, "_$1")
+        .toUpperCase()
+        .replace(/^_/, "") + "_FACET";
+
+      source += `    /// @notice Address of ${facetName} implementation\n`;
+      source += `    address constant ${constantName} = ${facetData.address};\n`;
+    }
+    source += "\n";
+
+    // Helper functions
+    source += "    // ========================================\n";
+    source += "    // Helper Functions\n";
+    source += "    // ========================================\n\n";
+
+    source += "    /**\n";
+    source += "     * @notice Get the Diamond contract address\n";
+    source += "     * @return The address of the deployed Diamond proxy\n";
+    source += "     */\n";
+    source += "    function getDiamondAddress() internal pure returns (address) {\n";
+    source += "        return DIAMOND_ADDRESS;\n";
+    source += "    }\n\n";
+
+    source += "    /**\n";
+    source += "     * @notice Get facet implementation address by name\n";
+    source += "     * @param facetName The name of the facet\n";
+    source += "     * @return The address of the facet implementation\n";
+    source += "     */\n";
+    source += "    function getFacetAddress(string memory facetName) internal pure returns (address) {\n";
+
+    let firstFacet = true;
+    for (const [facetName, facetData] of Object.entries(facets)) {
+      const constantName = facetName
+        .replace(/Facet$/, "")
+        .replace(/([A-Z])/g, "_$1")
+        .toUpperCase()
+        .replace(/^_/, "") + "_FACET";
+
+      const condition = firstFacet ? "if" : "else if";
+      source += `        ${condition} (keccak256(bytes(facetName)) == keccak256(bytes("${facetName}"))) {\n`;
+      source += `            return ${constantName};\n`;
+      source += "        }\n";
+      firstFacet = false;
+    }
+    source += "        return address(0);\n";
+    source += "    }\n";
+
+    source += "}\n";
+
+    return source;
+  }
+}

package/src/index.ts

@@ -0,0 +1,166 @@
+import { extendConfig, extendEnvironment, internalTask, task } from "hardhat/config";
+import "./tasks/deploy";
+import "./tasks/generate-helpers";
+import "./tasks/init";
+import "./tasks/test";
+import "./types/hardhat";
+
+import { existsSync, writeFileSync } from "fs";
+import {
+  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,
+} from "./foundry";
+import { validateConfig } from "./utils/validation";
+
+// Export framework classes for programmatic use
+export { DeploymentManager } from "./framework/DeploymentManager";
+export { ForgeFuzzingFramework } from "./framework/ForgeFuzzingFramework";
+export { HelperGenerator } from "./framework/HelperGenerator";
+
+// Export types
+export * from "./types/config";
+
+const TASK_INIT_FOUNDRY = "init-foundry";
+
+let pluginActivated = false;
+
+// Extend config with diamondsFoundry settings
+extendConfig((config, userConfig) => {
+  // Validate and set diamondsFoundry config
+  config.diamondsFoundry = validateConfig(userConfig.diamondsFoundry);
+
+  // Check foundry.toml presence. Don't warn when running foundry initialization task
+  if (!existsSync(path.join(config.paths.root, "foundry.toml"))) {
+    if (!process.argv.includes(TASK_INIT_FOUNDRY)) {
+      console.log(
+        picocolors.yellow(
+          `Warning: You are using the diamonds-hardhat-foundry plugin but there isn't a foundry.toml file in your project. Run 'npx hardhat ${TASK_INIT_FOUNDRY}' to create one.`
+        )
+      );
+    }
+    return;
+  }
+
+  // Load foundry config
+  const foundryConfig = getForgeConfig();
+
+  // Ensure required keys exist
+  if (
+    foundryConfig?.src === undefined ||
+    foundryConfig?.cache_path === undefined
+  ) {
+    throw new HardhatFoundryError(
+      "Couldn't find `src` or `cache_path` config keys after running `forge config --json`"
+    );
+  }
+
+  // Ensure foundry src path doesn't mismatch user-configured path
+  const userSourcesPath = userConfig.paths?.sources;
+  const foundrySourcesPath = foundryConfig.src;
+
+  if (
+    userSourcesPath !== undefined &&
+    path.resolve(userSourcesPath) !== path.resolve(foundrySourcesPath)
+  ) {
+    throw new HardhatFoundryError(
+      `User-configured sources path (${userSourcesPath}) doesn't match path configured in foundry (${foundrySourcesPath})`
+    );
+  }
+
+  // Set sources path
+  config.paths.sources = path.resolve(config.paths.root, foundrySourcesPath);
+
+  // Change hardhat's cache path if it clashes with foundry's
+  const foundryCachePath = path.resolve(
+    config.paths.root,
+    foundryConfig.cache_path
+  );
+  if (config.paths.cache === foundryCachePath) {
+    config.paths.cache = "cache_hardhat";
+  }
+
+  pluginActivated = true;
+});
+
+// Extend environment to add diamondsFoundry config to HRE
+extendEnvironment((hre: HardhatRuntimeEnvironment) => {
+  hre.diamondsFoundry = hre.config.diamondsFoundry;
+});
+
+// This task is in place to detect old hardhat-core versions
+internalTask(TASK_COMPILE_TRANSFORM_IMPORT_NAME).setAction(
+  async (
+    {
+      importName,
+      deprecationCheck,
+    }: { importName: string; deprecationCheck: boolean },
+    _hre
+  ): Promise<string> => {
+    // When the deprecationCheck param is passed, it means a new enough hardhat-core is being used
+    if (deprecationCheck) {
+      return importName;
+    }
+    throw new HardhatFoundryError(
+      "This version of diamonds-hardhat-foundry depends on hardhat version >= 2.17.2"
+    );
+  }
+);
+
+internalTask(TASK_COMPILE_GET_REMAPPINGS).setAction(
+  async (): Promise<Record<string, string>> => {
+    if (!pluginActivated) {
+      return {};
+    }
+
+    return getRemappings();
+  }
+);
+
+task(
+  TASK_INIT_FOUNDRY,
+  "Initialize foundry setup in current hardhat project",
+  async (_, hre: HardhatRuntimeEnvironment) => {
+    const foundryConfigPath = path.resolve(
+      hre.config.paths.root,
+      "foundry.toml"
+    );
+
+    if (existsSync(foundryConfigPath)) {
+      console.warn(
+        picocolors.yellow(`File foundry.toml already exists. Aborting.`)
+      );
+      process.exit(1);
+    }
+
+    console.log(`Creating foundry.toml file...`);
+
+    writeFileSync(
+      foundryConfigPath,
+      [
+        `[profile.default]`,
+        `src = '${path.relative(
+          hre.config.paths.root,
+          hre.config.paths.sources
+        )}'`,
+        `out = 'out'`,
+        `libs = ['node_modules', 'lib']`,
+        `test = '${path.relative(
+          hre.config.paths.root,
+          hre.config.paths.tests
+        )}'`,
+        `cache_path  = 'cache_forge'`,
+      ].join("\n")
+    );
+
+    await installDependency("foundry-rs/forge-std");
+  }
+);