feat: automatically generate reference from --help output (#1065)

* feat: gen help script

* chore: generate CLI reference

* update

* chisel

* hook it up

* split into multiple files

* chisel

* update

* attributes

* fix

* cleanup

* generate

* attributes

* update

.gitattributes

@@ -0,0 +1,5 @@
+src/output/**/* linguist-generated
+src/output/README.md -linguist-generated
+
+src/reference/cli/**/* linguist-generated
+src/reference/cli/README.md -linguist-generated

.gitignore

@@ -1,4 +1,8 @@
-book
-out
-cache
-.idea
+/book
+/.idea
+/.vscode
+
+/cache/
+/projects/**/cache/
+/out/
+/projects/**/out/

book.toml

@@ -6,6 +6,9 @@ src = "src"
 title = "Foundry Book"
 description = "A book on all things Foundry"
 
+[build]
+create-missing = false
+
 [output.html]
 git-repository-url = "https://github.com/foundry-rs/book"
 edit-url-template = "https://github.com/foundry-rs/book/edit/master/{path}"

scripts/common

@@ -8,6 +8,10 @@ set -eo pipefail
 ETH_RPC_URL="${ETH_RPC_URL:=https://eth-mainnet.alchemyapi.io/v2/Lc7oIGYeL_QvInzI0Wiu_pOZZDEKBrdf}"
 OUTPUT_DIR="$(realpath src/output)"
 ROOT="$(dirname "$(dirname "$(realpath "$0")")")"
+# shellcheck disable=SC2034
+SCRIPTS="$ROOT/scripts"
+
+export NO_COLOR=1
 
 # Runs a command and outputs text with anchors.
 # The anchors are:
@@ -28,17 +32,23 @@ run_command() {
     fi
   done
 
-  echo "Running $" "${escaped_cmd[@]}" >&2
+  echo "Running $" "${escaped_cmd[*]}" >&2
+  cmd_output=$("${cmd[@]}" | escape_colors)
+  print_anchored "${escaped_cmd[*]}" "$cmd_output" > "$output"
+}
 
-  cmd_output=$("${cmd[@]}" | sed "s,\x1B\[[0-9;]*[a-zA-Z],,g")
+escape_colors() {
+  sed "s,\x1B\[[0-9;]*[a-zA-Z],,g"
+}
 
-  cat > "$output" <<EOF
+print_anchored() {
+  cat > /dev/stdout <<EOF
 // ANCHOR: all
 // ANCHOR: command
-\$ ${escaped_cmd[@]}
+\$ $1
 // ANCHOR_END: command
 // ANCHOR: output
-$cmd_output
+$2
 // ANCHOR_END: output
 // ANCHOR_END: all
 EOF

scripts/gen_output.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+source "$(dirname "$0")/common"
+
+source "$SCRIPTS/gen_output/cast.sh"
+source "$SCRIPTS/gen_output/chisel.sh"
+source "$SCRIPTS/gen_output/forge.sh"
+source "$SCRIPTS/gen_output/help.sh"
+
+need_cmd git
+need_cmd mktemp
+need_cmd sed
+
+need_cmd forge
+need_cmd cast
+need_cmd anvil
+need_cmd chisel
+
+gen_help
+gen_cast
+gen_chisel
+gen_forge

scripts/gen_output/cast.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+gen_cast() {
+  source "$(dirname "$0")/common"
+
+  need_cmd cast
+
+  echo "Generating output (cast)..."
+  mkdir -p "$OUTPUT_DIR/cast"
+
+  run_command "$OUTPUT_DIR/cast/cast-call" \
+    cast call 0x6b175474e89094c44da98b954eedeac495271d0f "totalSupply()(uint256)" --rpc-url "$ETH_RPC_URL"
+
+  run_command "$OUTPUT_DIR/cast/cast-4byte-decode" \
+    cast 4byte-decode 0x1F1F897F676d00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003e7 \
+
+  echo OK.
+}

scripts/gen_output/chisel.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+gen_chisel() {
+  need_cmd chisel
+
+  echo "Generating output (chisel)..."
+
+  print_anchored \
+    "echo '!help' | chisel" \
+    "$(echo '!help' | chisel | escape_colors)" \
+    > "$OUTPUT_DIR/chisel/help"
+
+  echo OK.
+}

scripts/gen_output/forge.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+gen_forge() {
+  need_cmd git
+  need_cmd forge
+
+  echo "Generating output (forge)..."
+
+  in_temp hello_foundry
+  run_command "$OUTPUT_DIR/hello_foundry/forge-init" \
+    forge init hello_foundry
+  cd hello_foundry
+  run_command "$OUTPUT_DIR/hello_foundry/tree" \
+    tree . -d -L 1
+  run_command "$OUTPUT_DIR/hello_foundry/tree-with-files" \
+    tree . -L 3 -I output
+  run_command "$OUTPUT_DIR/hello_foundry/forge-build" \
+    forge build
+  run_command "$OUTPUT_DIR/hello_foundry/forge-test" \
+    forge test
+
+  in_temp foundry-template
+  git clone https://github.com/PaulRBerg/foundry-template
+  cd foundry-template
+  run_command "$OUTPUT_DIR/foundry-template/forge-install" \
+    forge install
+  run_command "$OUTPUT_DIR/foundry-template/forge-build" \
+    forge build
+  run_command "$OUTPUT_DIR/foundry-template/forge-test" \
+    forge test
+
+  in_temp deps
+  forge init deps
+  cd deps
+  run_command "$OUTPUT_DIR/deps/forge-install" \
+    forge install transmissions11/solmate
+  forge install d-xo/weird-erc20
+  run_command "$OUTPUT_DIR/deps/tree" \
+    tree lib -L 1
+  run_command "$OUTPUT_DIR/deps/forge-remappings" \
+    forge remappings
+
+  in_project test_filters
+  run_command "$OUTPUT_DIR/test_filters/forge-test-match-contract-and-test" \
+    forge test --match-contract ComplicatedContractTest --match-test test_Deposit
+
+  run_command "$OUTPUT_DIR/test_filters/forge-test-match-path" \
+    forge test --match-path test/ContractB.t.sol
+
+  in_project cheatcodes
+  run_command "$OUTPUT_DIR/cheatcodes/forge-test-simple" \
+    forge test --match-test test_IncrementAsOwner
+
+  run_command "$OUTPUT_DIR/cheatcodes/forge-test-cheatcodes" \
+    forge test --match-test "test_IncrementAsOwner|testFail_IncrementAsNotOwner" --match-path test/OwnerUpOnly.t.sol
+
+  run_command "$OUTPUT_DIR/cheatcodes/forge-test-cheatcodes-tracing" \
+    forge test -vvvv --match-test testFail_IncrementAsNotOwner --match-path test/OwnerUpOnly.t.sol
+
+  run_command "$OUTPUT_DIR/cheatcodes/forge-test-cheatcodes-expectrevert" \
+    forge test --match-test "test_IncrementAsOwner|test_IncrementAsNotOwner" --match-path test/OwnerUpOnly.t.sol
+
+  in_project fuzz_testing
+  step test/Safe.t.sol 1
+  run_command "$OUTPUT_DIR/fuzz_testing/forge-test-no-fuzz" \
+    forge test
+  step test/Safe.t.sol 2
+  run_command "$OUTPUT_DIR/fuzz_testing/forge-test-fail-fuzz" \
+    forge test --allow-failure
+  step test/Safe.t.sol 3
+  run_command "$OUTPUT_DIR/fuzz_testing/forge-test-success-fuzz" \
+    forge test
+
+  in_temp nft_tutorial
+  git clone https://github.com/FredCoen/nft-tutorial
+  cd nft-tutorial
+  forge install
+  forge build
+  run_command "$OUTPUT_DIR/nft_tutorial/forge-test" \
+    forge test
+
+  in_temp forge_tree
+  git clone https://github.com/FredCoen/nft-tutorial
+  cd nft-tutorial
+  forge install
+  run_command "$OUTPUT_DIR/forge_tree/forge-tree" \
+    forge tree
+  run_command "$OUTPUT_DIR/forge_tree/forge-tree-no-dedupe" \
+    forge tree --no-dedupe
+
+  echo OK.
+}