recon-generate

CLI to scaffold the Recon fuzzing suite (Chimera/Echidna/Medusa/Halmos targets) inside a Foundry project.

Installation

npm install -g recon-generate
# or from this repo
npm install -g .

For local dev:

npm install
npm run build
npm link   # optional, to use globally

Usage

Run from your Foundry project root (where foundry.toml is):

recon-generate [options]

Key options:

• --include "A,B:{foo(uint256)|bar(address)},C" — include-only these contracts/functions.
• --exclude "A:{foo(uint256)},D" — exclude these contracts/functions.
• --admin "A:{fnSig,fnSig}" — mark listed functions as admin (asAdmin).
• --mock "A,B" — generate mocks for the listed contracts (compiled ABIs required); mocks go under recon[-name]/mocks and are added to targets.
• --dynamic-deploy "Foo,Bar" — keep dynamic lists for the listed contracts: deploys one instance, tracks addresses in an array, exposes _getRandom<Contract> and switch<Contract>(entropy) helpers to rotate among deployed instances.
• --coverage — emit recon[-name]-coverage.json with source line ranges for included contract functions.
• --name <suite> — name the suite; affects folder (recon-<name>), config filenames (echidna-<name>.yaml, medusa-<name>.json, halmos-<name>.toml), and Crytic tester/runner names.
• --force — replace existing generated suite output under --output (does not rebuild .recon/out).
• --force-build — delete .recon/out to force a fresh compile before generation.
• --list — show available contracts/functions after filters, then exit.
• --debug — print filter/matching/debug info.
• --recon <path> — custom recon.json path (defaults to ./recon.json or ./.recon/recon.json).
• --output <path> — base path where the suite folder will be placed; we append /recon or /recon-<name>. Example: --output test → <foundry root>/test/recon-<name>.
• --foundry-config <path> — path to foundry.toml (default ./foundry.toml).

Examples:

# Default scaffolding
recon-generate

# Exclude a contract
recon-generate --exclude "Morpho" --force

# Exclude a single function only
recon-generate --exclude "Morpho:{setOwner(address)}" --force

# Mark specific functions as admin
recon-generate --admin "Morpho:{setOwner(address),enableIrm(address),setFee(MarketParams,uint256),setFeeRecipient(address)}" --force

# List what would be generated (no files written)
recon-generate --list --include "Morpho"

# Generate a named suite (outputs under recon-foo, configs echidna-foo.yaml, etc.)
recon-generate --name foo --force

# Generate mocks and include them in targets
recon-generate --mock "Morpho,Other" --force

# Enable dynamic deploy helpers for Foo and Bar
recon-generate --dynamic-deploy "Foo,Bar" --force

# Generate coverage JSON from a Crytic tester (no scaffolding)
recon-generate coverage --crytic-name CryticTester --name foo

# Link subcommand

After generating a suite you can update Echidna and Medusa configs with detected Foundry libraries:

```bash
recon-generate link

This runs crytic-compile with --foundry-compile-all to find linked libraries and rewrites:

• Echidna YAML cryticArgs and deployContracts with deterministic placeholder addresses
• Medusa compilation.platformConfig.args to include --compile-libraries

### Behavior

- If the suite output folder exists and `--force` is not provided, the command aborts.
- `--force` replaces the suite output folder; it does **not** rebuild `.recon/out`.
- `--force-build` deletes `.recon/out` to force a fresh compile before generation.
- When `--mock` is used, a fresh build is triggered, mocks are generated under `recon[-name]/mocks`, and a second build picks them up into `.recon/out` and targets.
- When `--dynamic-deploy` is used, generated `Setup.sol` keeps an `address[]` per listed contract, pushes the first deployment, and emits `_getRandom<Contract>` helper plus `switch<Contract>(entropy)` in `TargetFunctions.sol` to retarget to a previously deployed instance.
- `recon.json` is regenerated every run from current filters/contracts.
- Include/exclude/admin matching is tolerant of fully qualified struct names vs short names (e.g., `Morpho.MarketParams` vs `MarketParams`).
- Admin list sets `actor: admin` for matched functions; others default to `actor`.

### Development

```bash
npm install
npm run build
npm link   # to test globally