Update docs to mention including ast (#28)

Co-authored-by: Eric Lau <[email protected]>

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.1 (2024-03-20)
+
+- Throw helpful error message if AST not found in contract artifacts. ([#28](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades/pull/28))
+
 ## 0.2.0 (2024-03-20)
 
 - Update forge-std to v1.8.0, restrict state mutability of some functions. ([#30](https://github.com/OpenZeppelin/openzeppelin-foundry-upgrades/pull/30))

DEFENDER.md

@@ -16,17 +16,17 @@ See [README.md#installing](README.md#installing)
 ## Prerequisites
 1. Install [Node.js](https://nodejs.org/).  
 
-2. Configure your `foundry.toml` to include build info and storage layout:
+2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout:
 ```
 [profile.default]
+ffi = true
+ast = true
 build_info = true
 extra_output = ["storageLayout"]
 ```
 **Note**: Metadata must also be included in the compiler output, which it is by default.  
 
-3. Include `--ffi` in your `forge script` or `forge test` command.  
-
-4. Set the following environment variables in your `.env` file at your project root, using your Team API key and secret from OpenZeppelin Defender:
+3. Set the following environment variables in your `.env` file at your project root, using your Team API key and secret from OpenZeppelin Defender:
 ```
 DEFENDER_KEY=<Your API key>
 DEFENDER_SECRET<Your API secret>

README.md

@@ -43,15 +43,16 @@ This library uses the [OpenZeppelin Upgrades CLI](https://docs.openzeppelin.com/
 
 If you want to be able to run upgrade safety checks, the following are needed:
 1. Install [Node.js](https://nodejs.org/).
-2. Configure your `foundry.toml` to include build info and storage layout:
+2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout:
 ```
 [profile.default]
+ffi = true
+ast = true
 build_info = true
 extra_output = ["storageLayout"]
 ```
 3. If you are upgrading your contract from a previous version, add the `@custom:oz-upgrades-from <reference>` annotation to the new version of your contract according to [Define Reference Contracts](https://docs.openzeppelin.com/upgrades-plugins/1.x/api-core#define-reference-contracts) or specify the `referenceContract` option when calling the library's functions.
-4. Run `forge clean` before running your Foundry script or tests.
-5. Include `--ffi` in your `forge script` or `forge test` command.
+4. Run `forge clean` before running your Foundry script or tests, or include the `--force` option when running `forge script` or `forge test`.
 
 If you do not want to run upgrade safety checks, you can skip the above steps and use the `unsafeSkipAllChecks` option when calling the library's functions. Note that this is a dangerous option meant to be used as a last resort.
 

docs/modules/pages/foundry-defender.adoc

@@ -12,19 +12,20 @@ See xref:foundry-upgrades#installion[Using with Foundry - Installation].
 == Prerequisites
 1. Install https://nodejs.org/[Node.js].
 
-2. Configure your `foundry.toml` to include build info and storage layout:
+2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout:
 [source,toml]
 ----
 [profile.default]
+ffi = true
+ast = true
 build_info = true
 extra_output = ["storageLayout"]
 ----
 
 NOTE: Metadata must also be included in the compiler output, which it is by default.  
 
-3. Include `--ffi` in your `forge script` or `forge test` command.  
-
-4. Set the following environment variables in your `.env` file at your project root, using your Team API key and secret from OpenZeppelin Defender:
+[start=3]
+3. Set the following environment variables in your `.env` file at your project root, using your Team API key and secret from OpenZeppelin Defender:
 [source]
 ----
 DEFENDER_KEY=<Your API key>

docs/modules/pages/foundry-upgrades.adoc

@@ -41,19 +41,20 @@ If you want to be able to run upgrade safety checks, the following are needed:
 
 1. Install https://nodejs.org/[Node.js].
 
-2. Configure your `foundry.toml` to include build info and storage layout:
+2. Configure your `foundry.toml` to enable ffi, ast, build info and storage layout:
 [source,toml]
 ----
 [profile.default]
+ffi = true
+ast = true
 build_info = true
 extra_output = ["storageLayout"]
 ----
 
+[start=3]
 3. If you are upgrading your contract from a previous version, add the `@custom:oz-upgrades-from <reference>` annotation to the new version of your contract according to https://docs.openzeppelin.com/upgrades-plugins/1.x/api-core#define-reference-contracts[Define Reference Contracts] or specify the `referenceContract` option when calling the library's functions.
 
-4. Run `forge clean` before running your Foundry script or tests.
-
-5. Include `--ffi` in your `forge script` or `forge test` command.
+4. Run `forge clean` before running your Foundry script or tests, or include the `--force` option when running `forge script` or `forge test`.
 
 If you do not want to run upgrade safety checks, you can skip the above steps and use the `unsafeSkipAllChecks` option when calling the library's functions. Note that this is a dangerous option meant to be used as a last resort.
 

src/internal/Utils.sol

@@ -80,6 +80,11 @@ library Utils {
         );
         string memory artifactJson = vm.readFile(artifactPath);
 
+        if (!vm.keyExistsJson(artifactJson, ".ast")) {
+            revert(
+                string.concat("Could not find AST in artifact ", artifactPath, ". Set `ast = true` in foundry.toml")
+            );
+        }
         info.contractPath = vm.parseJsonString(artifactJson, ".ast.absolutePath");
         info.license = vm.parseJsonString(artifactJson, ".ast.license");
         info.sourceCodeHash = vm.parseJsonString(