v0.3.0 (#164)

* feat: Add minimal fe support * fix: fix tests for fe module * chore: fmt * chore: attempt to install fe on workflow * fix: add url to curl command * fix: fix curl command * Invariant testing base contract * Complete invariants module and add bound function from forge-std * forge fmt * chore: use fe v0.24.0 * docs: add docs for the `Fe` module. * chore: export `fe` from `script.sol` * chore: export `Fe` struct from `script.sol` * chore: export huff from script.sol * fix: fix Fe module import on script.sol * feat: add method to create multiple addresses * chore: rename method * empty * Add invariant functions that receive arrays * Add docs * Add docs * Format * Fix docs * fix: fix Fe module documentation * fix: json safe create and improve accounts * feat: use tryFfi on commands (#136) * feat: use tryFfi on commands * style: fmt * feat: use CommandResult instead of FfiResult * chore: remove Hevm copy and replace with ad hoc interface * chore: extend CommandResult * chore: update function names * chore: use unwrap/expect as function names * style: fmt * test: improve unwrap test * style: fmt * docs: update commands docs (#142) * docs: update commands docs * docs: add expect example * chore: remove console unused imports * chore: update unwrap error format (#145) * chore: make output dir optional when building Fe code (#149) * chore: add `rawConsoleLog` function (#152) * feat: add `rawConsoleLog` function Add a `rawConsoleLog` function to prevent compiling the whole `console` contract from `forge-std`. Resolves #120 * chore: use println instead of rawConsoleLog * feat: adds createMay(length, prefix) (#150) Adds a new function to the `accounts` module `createMany(length, prefix)` that creates an array of addresses of a specified length and applies a label to each one with a prefix `prefix` in the form of `{prefix}_{i}`. * chore: add formatError function (#153) * chore: add `formatError` function add `formatError` function to standardize Vulcan error messages. Resolves #105 * chore: add formatError to accounts * chore: progress adding formatError to modules * chore: add formatError to fmt * chore: add formatError to missing modules * chore: update forge-std to commit 1d9650e (#157) * chore: remove TryFfi interface (#159) Removes the `TryFfi` interface and uses the `forge-std` `Vm` `tryFfi` method directly. * docs: update vulcan version to 0.3.0 * docs: update installation guide vulcan version * chore(main): release 0.3.0 * chore: setup husky and commitlint (#161) --------- Co-authored-by: Vicente Dragicevic <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
nomoixyz · Sep 1, 2023 · a846bee · a846bee
1 parent 658e96f
commit a846bee
Show file tree

Hide file tree

Showing 43 changed files with 3,234 additions and 104 deletions.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -28,6 +28,11 @@ jobs:
         with:
           version: nightly
 
+      - name: Install Fe
+        run: |
+          curl -L https://github.com/ethereum/fe/releases/download/v0.24.0/fe_amd64 -o /usr/local/bin/fe -s
+          chmod +x /usr/local/bin/fe
+
       - name: Run Forge build
         run: |
           forge --version
@@ -52,4 +57,4 @@ jobs:
         run: forge --version
 
       - name: Check formatting
-        run: forge fmt --check
+        run: forge fmt --check
diff --git a/.gitignore b/.gitignore
@@ -11,3 +11,9 @@ out/
 .env
 
 .DS_Store
+
+# Test stuff
+test/fixtures/fe
+
+# Node stuff
+node_modules
diff --git a/.husky/commit-msg b/.husky/commit-msg
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx --no -- commitlint --edit ${1}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.3.0](https://github.com/nomoixyz/vulcan/compare/v0.2.0...v0.3.0) (2023-09-01)
+
+
+### Features
+
+* add function to create empty command ([2c31886](https://github.com/nomoixyz/vulcan/commit/2c31886075fae5a5177410739309ff38ed834f2a))
+* export Command struct from script.sol ([c88883a](https://github.com/nomoixyz/vulcan/commit/c88883a402ccfae6aa2d0de674936ba22e3d3514))
+
+
+### Bug Fixes
+
+* fix return natspect documentation ([5da4ad1](https://github.com/nomoixyz/vulcan/commit/5da4ad14fbe07b35d29260fe2cb97ffb2cb95de3))
+* tabs ([1d4c0b9](https://github.com/nomoixyz/vulcan/commit/1d4c0b9d350445825d84198c7b242f5e432ffb39))
+* update code examples ([953d661](https://github.com/nomoixyz/vulcan/commit/953d661e1a84e84b9a40b8f8178980ea32d0ef96))
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ Over time, Vulcan will grow to include more functionality and utilities, eventua
 ## Installation
 
 ```
-$ forge install nomoixyz/vulcan@v0.2.0
+$ forge install nomoixyz/vulcan@v0.3.0
 ```
 
 ## Usage

diff --git a/commitlint.config.js b/commitlint.config.js
@@ -0,0 +1 @@
+module.exports = {extends: ['@commitlint/config-conventional']}
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -14,6 +14,7 @@
     - [Context](./modules/context.md)
     - [Env](./modules/env.md)
     - [Events](./modules/events.md)
+    - [Fe](./modules/fe.md)
     - [Format](./modules/fmt.md)
     - [Forks](./modules/forks.md)
     - [Fs](./modules/fs.md)
@@ -32,10 +33,12 @@
     - [Context](./reference/modules/context.md)
     - [Env](./reference/modules/env.md)
     - [Events](./reference/modules/events.md)
+    - [Fe](./reference/modules/fe.md)
     - [Format](./reference/modules/fmt.md)
     - [Forks](./reference/modules/forks.md)
     - [Fs](./reference/modules/fs.md)
     - [Huff](./reference/modules/huff.md)
+    - [Invariants](./reference/modules/invariants.md)
     - [Json](./reference/modules/json.md)
     - [Strings](./reference/modules/strings.md)
     - [Watchers](./reference/modules/watchers.md)

diff --git a/docs/src/guide/installation.md b/docs/src/guide/installation.md
@@ -2,5 +2,5 @@
 
 In an existing Foundry project, use `forge install`:
 ```
-$ forge install nomoixyz/vulcan@0.1.0
+$ forge install nomoixyz/vulcan@0.3.0
 ```
diff --git a/docs/src/modules/commands.md b/docs/src/modules/commands.md
@@ -4,15 +4,29 @@ Execute external commands. The `ffi` setting must be enabled on `foundry.toml` f
 work.
 
 ```solidity
-import { Test, Command, commands } from "vulcan/test.sol";
+import { Test, Command, commands, CommandResult } from "vulcan/test.sol";
 
 contract TestMyContract is Test {
     using commands for *;
 
     function testMyContract() external {
         // run `echo Hello World`.
         // There is no need to create a dynamic array for the arguments
-        bytes memory res = commands.run(["echo", "Hello World"]);
+        CommandResult memory res = commands.run(["echo", "Hello World"]);
+
+        if (res.isOk()) {
+            // do something
+        }
+
+        if (res.isError()) {
+            // do something else
+        }
+
+        // This will return the output from `stdout` or revert if the command failed.
+        bytes memory output = res.unwrap();
+
+        // or provide a custom error message in case the command execution fails.
+        output = res.expect("Somehow echo failed");
 
         // A comand can be created to facilitate multiple executions
         Command memory cmd = commands.create("echo").arg("Hello World");

diff --git a/docs/src/modules/fe.md b/docs/src/modules/fe.md
@@ -0,0 +1,25 @@
+# Fe
+
+Provides [Fe](https://fe-lang.org/) compiler support. The `ffi` setting must be enabled on `foundry.toml` for this module
+to work.
+
+```solidity
+import { Test, fe } from "vulcan/test.sol";
+
+contract TestMyContract is Test {
+    function testCompile() external {
+        fe
+            .create()
+            .setFilePath("./test/mocks/guest_book.fe")
+            .setOutputDir("./test/fixtures/fe/output")
+            .setOverwrite(true)
+            .build()
+            .unwrap();
+
+        bytes memory bytecode = fe.getBytecode("GuestBook");
+    }
+
+}
+```
+[**Fe API reference**](../reference/modules/fe.md)
+
diff --git a/docs/src/reference/modules/commands.md b/docs/src/reference/modules/commands.md
@@ -74,69 +74,86 @@ Creates a new `Command` struct using the provided `input` as the executable.
 #### **`args(Command self, string[20] _args) → (Command)`**
 
 
-#### **`run(Command self) → (bytes)`**
+#### **`run(Command self) → (CommandResult)`**
 
-Runs a command using the specified `Command` struct as parameters and returns the result.
+Runs a command using the specified `Command` struct as parameters and returns a `CommandResult`
+struct.
 
-#### **`run(string[] inputs) → (bytes)`**
+#### **`run(string[] inputs) → (CommandResult)`**
 
-Runs a command with the specified `inputs` as parameters and returns the result.
+Runs a command with the specified `inputs` as parameters and returns a `CommandResult` struct.
 
-#### **`run(string[1] inputs) → (bytes)`**
+#### **`isOk(CommandResult self) → (bool)`**
 
+Returns `true` if the command ran successfully and `false` otherwise.
 
-#### **`run(string[2] inputs) → (bytes)`**
+#### **`isError(CommandResult self) → (bool)`**
 
+Returns `true` if the command failed and `false` otherwise.
 
-#### **`run(string[3] inputs) → (bytes)`**
+#### **`unwrap(CommandResult self) → (bytes)`**
 
+Returns the output from `stdout` or reverts if the command failed to run.
 
-#### **`run(string[4] inputs) → (bytes)`**
+#### **`expect(CommandResult self, string customError) → (bytes)`**
 
+Returns the output from `stdout` or reverts with `customError` if the command failed to run.
 
-#### **`run(string[5] inputs) → (bytes)`**
+#### **`run(string[1] inputs) → (CommandResult)`**
 
 
-#### **`run(string[6] inputs) → (bytes)`**
+#### **`run(string[2] inputs) → (CommandResult)`**
 
 
-#### **`run(string[7] inputs) → (bytes)`**
+#### **`run(string[3] inputs) → (CommandResult)`**
 
 
-#### **`run(string[8] inputs) → (bytes)`**
+#### **`run(string[4] inputs) → (CommandResult)`**
 
 
-#### **`run(string[9] inputs) → (bytes)`**
+#### **`run(string[5] inputs) → (CommandResult)`**
 
 
-#### **`run(string[10] inputs) → (bytes)`**
+#### **`run(string[6] inputs) → (CommandResult)`**
 
 
-#### **`run(string[11] inputs) → (bytes)`**
+#### **`run(string[7] inputs) → (CommandResult)`**
 
 
-#### **`run(string[12] inputs) → (bytes)`**
+#### **`run(string[8] inputs) → (CommandResult)`**
 
 
-#### **`run(string[13] inputs) → (bytes)`**
+#### **`run(string[9] inputs) → (CommandResult)`**
 
 
-#### **`run(string[14] inputs) → (bytes)`**
+#### **`run(string[10] inputs) → (CommandResult)`**
 
 
-#### **`run(string[15] inputs) → (bytes)`**
+#### **`run(string[11] inputs) → (CommandResult)`**
 
 
-#### **`run(string[16] inputs) → (bytes)`**
+#### **`run(string[12] inputs) → (CommandResult)`**
 
 
-#### **`run(string[17] inputs) → (bytes)`**
+#### **`run(string[13] inputs) → (CommandResult)`**
 
 
-#### **`run(string[18] inputs) → (bytes)`**
+#### **`run(string[14] inputs) → (CommandResult)`**
 
 
-#### **`run(string[19] inputs) → (bytes)`**
+#### **`run(string[15] inputs) → (CommandResult)`**
 
 
-#### **`run(string[20] inputs) → (bytes)`**
+#### **`run(string[16] inputs) → (CommandResult)`**
+
+
+#### **`run(string[17] inputs) → (CommandResult)`**
+
+
+#### **`run(string[18] inputs) → (CommandResult)`**
+
+
+#### **`run(string[19] inputs) → (CommandResult)`**
+
+
+#### **`run(string[20] inputs) → (CommandResult)`**
diff --git a/docs/src/reference/modules/fe.md b/docs/src/reference/modules/fe.md
@@ -0,0 +1,45 @@
+# Fe
+
+#### **`create() → (Fe)`**
+
+Creates a new `Fe` struct with the following defaults.
+
+```solidity
+Fe({
+    compilerPath: "fe",
+    filePath: "",
+    outputDir: "",
+    overwrite: false
+});
+```
+
+> Notice: The `filePath` is the only required field, if it is empty, `.build` and `.toCommand`
+> will revert.
+
+#### **`build(Fe self) → (bytes)`**
+
+Builds a binary file from a `.fe` file.
+
+#### **`toCommand(Fe self) → (Command)`**
+
+Converts the `Fe` struct into a `Command` struct.
+
+#### **`setCompilerPath(Fe self, string compilerPath) → (Fe)`**
+
+Overwrites the compiler path.
+
+#### **`setFilePath(Fe self, string filePath) → (Fe)`**
+
+Overwrites the file path.
+
+#### **`setOutputDir(Fe self, string outputDir) → (Fe)`**
+
+Overwrites the default artifacts directory.
+
+#### **`setOverwrite(Fe memory self, bool overwrite) → (Fe)`**
+
+Sets the build command overwrite flag. If `true` the contents of `outputDir` will be overwritten.
+
+#### **`getBytecode(Fe memory self, string contractName) → (bytes)`**
+
+Returns the bytecode from a compiled `Fe` contract.
diff --git a/docs/src/reference/modules/invariants.md b/docs/src/reference/modules/invariants.md
@@ -0,0 +1,73 @@
+# Invariants
+
+ ```solidity
+ struct FuzzSelector {
+    address addr;
+    bytes4[] selectors;
+}
+```
+
+#### **`excludeContract(address newExcludedContract)`**
+
+Excludes a contract from the invariant runs. This means that no transactions will be sent to this contract.
+
+#### **`excludeContracts(address[] memory newExcludedContracts)`**
+
+Excludes multiple contracts from the invariant runs. This means that no transactions will be sent to these contracts.
+
+#### **`excludeSender(address newExcludedSender)`**
+
+Excludes a sender from the invariant runs. This means that the address will not be used as the sender of a transaction.
+
+#### **`excludeSenders(address[] memory newExcludedSenders)`**
+
+Excludes multiple senders from the invariant runs. This means that these addresses will not be used as the senders of transactions.
+
+#### **`excludeArtifact(string memory newExcludedArtifact)`**
+
+Excludes an artifact from the invariant runs. This means that contracts with this artifact will not be targeted.
+
+#### **`excludeArtifacts(string[] memory newExcludedArtifacts)`**
+
+Excludes multiple artifacts from the invariant runs. This means that contracts with these artifacts will not be targeted.
+
+#### **`targetArtifact(string memory newTargetedArtifact)`**
+
+Targets an artifact in the invariant runs. This means that contracts with this artifact will be specifically targeted.
+
+#### **`targetArtifacts(string[] memory newTargetedArtifacts)`**
+
+Targets multiple artifacts in the invariant runs. This means that contracts with these artifacts will be specifically targeted.
+
+#### **`targetArtifactSelector(FuzzSelector memory newTargetedArtifactSelector)`**
+
+Targets an artifact selector in the invariant runs. This means that the specific artifact selector will be targeted.
+
+#### **`targetArtifactSelectors(FuzzSelector[] memory newTargetedArtifactSelectors)`**
+
+Targets multiple artifact selectors in the invariant runs. This means that these specific artifact selectors will be targeted.
+
+#### **`targetContract(address newTargetedContract)`**
+
+Targets a contract in the invariant runs. This means that transactions will be specifically sent to this contract.
+
+#### **`targetContracts(address[] memory newTargetedContracts)`**
+
+Targets multiple contracts in the invariant runs. This means that transactions will be specifically sent to these contracts.
+
+#### **`targetSelector(FuzzSelector memory newTargetedSelector)`**
+
+Targets a selector in the invariant runs. This means that the specific selector will be targeted.
+
+#### **`targetSelectors(FuzzSelector[] memory newTargetedSelectors)`**
+
+Targets multiple selectors in the invariant runs. This means that these specific selectors will be targeted.
+
+#### **`targetSender(address newTargetedSender)`**
+
+Targets a sender in the invariant runs. This means that the address will be specifically used as the sender of a transaction.
+
+#### **`targetSenders(address[] memory newTargetedSenders)`**
+
+Targets multiple senders in the invariant runs. This means that these addresses will be specifically used as the senders of transactions.
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		module.exports = {extends: ['@commitlint/config-conventional']}