diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 5de84b24..c30fd8a5 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -324,7 +324,7 @@ jobs: run: cargo make schema - name: Generate documentations - run: cargo make docs-generate + run: cargo make docs - name: Verify changed docs files uses: tj-actions/verify-changed-files@v20 @@ -342,7 +342,52 @@ jobs: echo "β€£ Changes in $file:" git diff HEAD $file done - echo "Please generate docs using \`cargo make docs-generate\` then commit this new documentation." + echo "Please generate docs using \`cargo make docs\` then commit this new documentation." + exit 1 + + check-readme-updated: + runs-on: ubuntu-22.04 + steps: + - name: Check out repository + uses: actions/checkout@v5 + + - name: Cache cargo registry + uses: actions/cache@v4 + with: + path: | + ~/.cargo/registry + ~/.cargo/git + ~/.cargo/bin + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + restore-keys: | + ${{ runner.os }}-cargo- + + - name: Setup rust + uses: actions-rust-lang/setup-rust-toolchain@v1 + + - name: Install cargo make + uses: davidB/rust-cargo-make@v1 + + - name: Generate readme + run: cargo make readme + + - name: Verify changed readme files + uses: tj-actions/verify-changed-files@v20 + id: verify-changed-readme-files + with: + files: | + README.md + + - name: Run step only when files change. + if: steps.verify-changed-readme-files.outputs.files_changed == 'true' + run: | + echo "❌ README.md has been updated." + echo " Changed files : ${{ steps.verify-changed-readme-files.outputs.changed_files }}" + git diff --name-only | grep 'README.md' | while read file; do + echo "β€£ Changes in $file:" + git diff HEAD $file + done + echo "Please generate readme using \`cargo make readme\` then commit this new documentation." exit 1 lint-typos: diff --git a/.releaserc.cjs b/.releaserc.cjs index c513b14c..b3d8d6dc 100644 --- a/.releaserc.cjs +++ b/.releaserc.cjs @@ -77,7 +77,7 @@ module.exports = { "@semantic-release/exec", { prepareCmd: - "cargo make schema && cargo make docs-generate && cargo make release-wasm", + "cargo make schema && cargo make docs && cargo make release-wasm", }, ], [ diff --git a/Makefile.toml b/Makefile.toml index cdd41ef8..cf1a6edd 100644 --- a/Makefile.toml +++ b/Makefile.toml @@ -1,70 +1,127 @@ +[tasks.default] +alias = "help" + +[tasks.help] +category = "Help" +description = "Display available tasks" +script = [ + "cargo make --silent --list-all-steps --hide-uninteresting", + "echo", + "echo 'Examples:'", + "echo ' cargo make build'", + "echo ' cargo make wasm'", + "echo ' cargo make test'", + "echo ' cargo make format'", + "echo ' cargo make lint'", +] + [tasks.format-rust] +category = "Code Quality" dependencies = ["install-cargo-sort-derives"] description = "Format rust sources files. (rustfmt provided by rust-toolchain.toml)" script = ["cargo fmt", "cargo sort-derives"] [tasks.lint-rust-format] +category = "Code Quality" dependencies = ["install-cargo-sort-derives"] description = "Check formatting and derives order (rustfmt via rust-toolchain.toml)." script = ["cargo fmt --all -- --check", "cargo sort-derives --check"] -[tasks.lint-rust] +[tasks.lint-rust-clippy] args = ["cranky"] +category = "Code Quality" command = "cargo" dependencies = ["install-cranky"] description = "Check lint of all sources files (clippy via rust-toolchain.toml)." +[tasks.lint-rust] +category = "Code Quality" +dependencies = ["lint-rust-format", "lint-rust-clippy"] +description = "Check all Rust linting (formatting and clippy)." + [tasks.lint-toml] args = ["lint"] +category = "Code Quality" command = "taplo" dependencies = ["install-taplo-cli"] description = "Check lint of all toml files." -[tasks.lint-cargo-toml] -script = ''' -find . -type f \( -name "Cargo.toml" \) -print0 | xargs -0 -n1 cargo make lint-cargo-toml-file -''' - [tasks.lint-cargo-toml-file] args = ["${@}"] +category = "Code Quality" command = "cargo-toml-lint" dependencies = ["install-cargo-toml-lint"] description = "Check lint of the given toml file" +[tasks.lint-cargo-toml] +category = "Code Quality" +description = "Check lint of all Cargo.toml files." +script = ''' +find . -type f \( -name "Cargo.toml" \) -print0 | xargs -0 -n1 cargo make lint-cargo-toml-file +''' + [tasks.lint-cargo-deps] args = ["machete", "--with-metadata"] +category = "Code Quality" command = "cargo" dependencies = ["install-cargo-machete"] +description = "Check for unused dependencies." + +[tasks.lint-cargo] +category = "Code Quality" +dependencies = ["lint-cargo-toml", "lint-cargo-deps"] +description = "Check all Cargo linting (toml files and dependencies)." [tasks.format-toml] args = ["fmt"] +category = "Code Quality" command = "taplo" dependencies = ["install-taplo-cli"] description = "Format toml file" [tasks.lint] -dependencies = ["lint-rust-format", "lint-rust", "lint-toml"] +category = "Code Quality" +dependencies = ["lint-rust", "lint-cargo", "lint-toml"] +description = "Check all linting (Rust, Cargo, and TOML)." [tasks.format] +category = "Code Quality" dependencies = ["format-rust", "format-toml"] +description = "Format all files (Rust and TOML)." -[tasks.clean] +[tasks.clean-cargo] args = ["clean"] +category = "Cleanup" command = "cargo" +description = "Clean cargo build artifacts." + +[tasks.clean] +category = "Cleanup" +dependencies = ["clean-cargo", "clean-docs", "clean-chain"] +description = "Clean all artifacts (cargo, docs, and chain)." [tasks.build] args = ["build", "--release", "--locked"] +category = "Build" command = "cargo" -[tasks.test] +[tasks.test-unit] args = ["test", "--lib", "--tests", "--workspace", "--locked"] +category = "Testing" command = "cargo" description = "Run all unit tests." [tasks.test-coverage] args = ["llvm-cov", "--workspace", "--lcov", "--output-path", "lcov.info"] +category = "Testing" command = "cargo" dependencies = ["install-llvm-cov"] +description = "Run tests with coverage reporting." + +[tasks.test] +category = "Testing" +dependencies = ["test-unit"] +description = "Run all tests." [tasks.wasm] args = [ @@ -76,26 +133,32 @@ args = [ "wasm32-unknown-unknown", "--locked", ] +category = "Build" command = "cargo" dependencies = ["install-cargo-hack"] [tasks.schema] +category = "Build" workspace = true [tasks.check-contracts] +category = "Verification" dependencies = ["install-cosmwasm-check", "wasm"] +description = "Check WASM contracts validity." script = ''' cosmwasm-check ${DIR_WASM}/*.wasm ''' -[tasks.docs-clean] -description = "Clean documentation folder" +[tasks.clean-docs] +category = "Cleanup" +description = "Clean documentation folder." script = ''' echo "🧹 Cleaning documentation folder" rm -rf ${DOCS_FOLDER}/* ''' [tasks.check-npx] +category = "Verification" description = "Check npx is installed" script = ''' if ! command -v npx >/dev/null 2>&1; then @@ -106,6 +169,7 @@ fi ''' [tasks.check-awk] +category = "Verification" description = "Check awk is installed" script = ''' if ! command -v awk >/dev/null 2>&1; then @@ -116,6 +180,7 @@ fi ''' [tasks.check-perl] +category = "Verification" description = "Check perl is installed" script = ''' if ! command -v perl >/dev/null 2>&1; then @@ -126,6 +191,7 @@ fi ''' [tasks.check-jq] +category = "Verification" description = "Check jq is installed (version 1.7 or higher, but below 2.0)" script = ''' if ! command -v jq >/dev/null 2>&1; then @@ -153,14 +219,21 @@ fi ''' [tasks.check-prerequisites] +category = "Verification" dependencies = ["check-npx", "check-awk", "check-perl", "check-jq"] -description = "Check all the prerequisites are installed" +description = "Check all the prerequisites are installed." script = ''' echo "βœ… All prerequisites are satisfied" ''' -[tasks.docs-generate] -dependencies = ["check-prerequisites", "docs-clean", "schema"] +[tasks.check] +category = "Verification" +dependencies = ["check-prerequisites", "check-contracts"] +description = "Check all requirements (prerequisites and contracts)." + +[tasks.docs] +category = "Documentation" +dependencies = ["check-prerequisites", "clean-docs", "schema"] description = "Generate documentation" script = ''' echo "🧹 Cleaning old documentation..." @@ -247,6 +320,7 @@ echo "πŸ“– Documentation has been successfully generated and available at $(pwd) ''' [tasks.release-wasm] +category = "Build" description = "Build optimized wasm using CosmWasm optimizer and provide checksums" script = ''' echo "πŸ“¦ Generating release binaries and checksums into ${DIR_WASM}" @@ -256,16 +330,18 @@ docker run --rm -v "$(pwd)":/code \ ${DOCKER_IMAGE_COSMWASM_OPTIMIZER} ''' -[tasks.chain-clean] +[tasks.clean-chain] +category = "Cleanup" condition = { fail_message = "🚫 The chain is running" } condition_script = ["! docker ps -a | grep ${CHAIN} > /dev/null"] -description = "Clean the chain data (⚠️ definitively)" +description = "Clean the chain data (⚠️ definitively)." script = ''' echo "️🧹Cleaning chain ${CHAIN} under ${CHAIN_HOME}" rm -rf ${CHAIN_HOME} ''' [tasks.chain-init-folder] +category = "Chain Management" description = "Initialize deploy folder to make sure scripts have the right permission (needed for linux)" script = ''' echo "️✨ Create deploy folder structure" @@ -276,6 +352,7 @@ mkdir -p ${DIR_DEPLOY}/${CHAIN}/data ''' [tasks.chain-add-keys] +category = "Chain Management" condition = { fail_message = "🚫 The chain is already initialized." } condition_script = ["[ ! -f ${CHAIN_HOME}/config/genesis.json ]"] dependencies = ["chain-init-folder"] @@ -304,6 +381,7 @@ done ''' [tasks.chain-initialize] +category = "Chain Management" condition = { fail_message = "🚫 The chain is already initialized." } condition_script = ["[ ! -f ${CHAIN_HOME}/config/genesis.json ]"] dependencies = ["chain-add-keys"] @@ -366,6 +444,7 @@ sed -i ${SED_FLAG} 's/"stake"/"uaxone"/g' ${CHAIN_HOME}/config/genesis.json ''' [tasks.chain-start] +category = "Chain Management" condition = { fail_message = "🚫 The chain is already running" } condition_script = ["! docker ps -a | grep ${CHAIN} > /dev/null"] description = "Run the full node axoned application using the chain's home directory under a Docker container." @@ -389,6 +468,7 @@ docker run -d \ ''' [tasks.chain-stop] +category = "Chain Management" condition = { fail_message = "🚫 The chain is not running" } condition_script = ["docker ps -a | grep ${CHAIN} > /dev/null"] description = "Stop the chain's container." @@ -399,6 +479,7 @@ docker rm ${CHAIN} ''' [tasks.chain-logs] +category = "Chain Management" condition = { fail_message = "🚫 The chain is not running" } condition_script = ["docker ps -a | grep ${CHAIN} > /dev/null"] description = "Show the chain's container logs." @@ -408,6 +489,7 @@ docker logs -f ${CHAIN} ''' [tasks.chain] +category = "Chain Management" description = "Run the axoned CLI using the chain's home directory under a Docker container." script = ''' echo "⌨️ Executing ${DOCKER_IMAGE_AXONEPROTOCOL_AXONED} ${@}..." @@ -423,6 +505,7 @@ docker run \ ''' [tasks.chain-deploy-contract] +category = "Contract Deployment" dependencies = ["chain-start"] description = "Deploy a specific contract to the chain. The contract must be compiled and the wasm file must be present in the artifacts directory (under target/wasm32-unknown-unknown/...)." script = ''' @@ -455,6 +538,7 @@ docker run --rm \ ''' [tasks.chain-deploy-contracts] +category = "Contract Deployment" description = "Deploy all the available contracts to the chain (under target/wasm32-unknown-unknown/...)." script = ''' find "${DIR_WASM}" -type f -name "*.wasm" -maxdepth 1 | while read file; do @@ -465,6 +549,7 @@ done ''' [tasks.chain-list-contracts] +category = "Contract Deployment" description = "List all the contracts deployed to the chain." script = ''' echo "πŸ” Listing contracts on chain ${CHAIN}" @@ -479,6 +564,7 @@ docker run --rm \ ''' [tasks.chain-inspect-contract] +category = "Contract Deployment" description = "Inspect a specific contract deployed to the chain." script = ''' if [ -z "$1" ] @@ -497,6 +583,7 @@ docker run --rm \ ''' [tasks.chain-instantiate-contract] +category = "Contract Interaction" dependencies = ["chain-start"] description = "Instantiate a specific contract to the chain. The contract must be already deployed." script = ''' @@ -545,6 +632,7 @@ docker run --rm \ ''' [tasks.chain-query-contract] +category = "Contract Interaction" dependencies = ["chain-start"] description = "Query a specific contract to the chain. The contract must be already deployed and instantiated." script = ''' @@ -574,6 +662,7 @@ docker run --rm \ ''' [tasks.chain-execute-contract] +category = "Contract Interaction" dependencies = ["chain-start"] description = "Execute a command on a specific contract to the chain. The contract must be already deployed and instantiated." script = ''' @@ -615,36 +704,60 @@ docker run --rm \ ''' [tasks.install-cranky] +category = "Development Tools" install_crate = { crate_name = "cargo-cranky", min_version = "0.3.0" } [tasks.install-taplo-cli] +category = "Development Tools" install_crate = { crate_name = "taplo-cli", binary = "taplo", test_arg = "--help", min_version = "0.9.0" } [tasks.install-cargo-toml-lint] +category = "Development Tools" install_crate = { crate_name = "cargo-toml-lint", min_version = "0.1.1" } [tasks.install-llvm-cov] +category = "Development Tools" install_crate = { crate_name = "cargo-llvm-cov", min_version = "0.6.9" } install_crate_args = ["--force"] [tasks.install-cosmwasm-check] +category = "Development Tools" install_crate = { crate_name = "cosmwasm-check", min_version = "2.2.2" } [tasks.install-cargo-workspaces] +category = "Development Tools" install_crate = { crate_name = "cargo-workspaces", binary = "cargo", test_arg = [ "workspaces", "--help", ], min_version = "0.3.6" } [tasks.install-cargo-hack] +category = "Development Tools" install_crate = { crate_name = "cargo-hack", min_version = "0.6.14" } [tasks.install-cargo-machete] +category = "Development Tools" install_crate = { crate_name = "cargo-machete", min_version = "0.7.0" } [tasks.install-cargo-sort-derives] +category = "Development Tools" install_crate = { crate_name = "cargo-sort-derives", min_version = "0.10.0" } +[tasks.install] +category = "Development Tools" +dependencies = [ + "install-cranky", + "install-taplo-cli", + "install-cargo-toml-lint", + "install-llvm-cov", + "install-cosmwasm-check", + "install-cargo-workspaces", + "install-cargo-hack", + "install-cargo-machete", + "install-cargo-sort-derives", +] +description = "Install all required development tools." + [tasks.publish-crates] args = [ "workspaces", @@ -654,14 +767,63 @@ args = [ "--no-git-commit", "skip", ] +category = "Publishing" command = "cargo" condition = { env_set = ["CARGO_REGISTRY_TOKEN"] } dependencies = ["install-cargo-workspaces"] description = "Publish all crates to the registry. Requires CARGO_REGISTRY_TOKEN to be set." +[tasks.readme] +category = "Documentation" +description = "Update README with help output" +script = ''' +set -euo pipefail + +HELP_OUTPUT="$(cargo make --silent --makefile ./Makefile.toml --list-all-steps --hide-uninteresting)" +BLOCK_FILE="$(mktemp -t readme_tasks_block.XXXXXX)" +trap 'rm -f "$BLOCK_FILE"' EXIT + +{ + printf '%s\n' '' + printf '%s\n' '```text' + printf '%s\n' "${HELP_OUTPUT}" + printf '%s\n' '```' + printf '%s\n' '' +} > "${BLOCK_FILE}" + +awk -v blk="${BLOCK_FILE}" ' + BEGIN{ + start=""; end=""; + replaced=0; inside=0; + while ((getline l < blk) > 0) block = block l ORS; + close(blk); + } + { + if (!replaced && index($0, start)) { + printf "%s", block; # no extra ORS + inside=1; replaced=1; next; + } + if (inside) { + if (index($0, end)) { inside=0; next } + next + } + print + } + END{ + if (!replaced) { + printf "%s", block + } + } +' README.md > README.md.__new__ && mv README.md.__new__ README.md + +echo "βœ… README.md updated" +''' +script_runner = "bash" + [config] default_to_workspace = false min_version = "0.36.3" +skip_core_tasks = true [env] CARGO_MAKE_CRATE_INSTALLATION_LOCKED = true diff --git a/README.md b/README.md index 3b8beafb..cccf1736 100644 --- a/README.md +++ b/README.md @@ -83,6 +83,108 @@ And the following common [GNU Core utilities](https://en.wikipedia.org/wiki/List - [shasum](https://linuxhint.com/shasum-linux/) v6.02 or higher - [sed](https://www.gnu.org/software/sed/) v4.8 or higher +### πŸ› οΈ Available Tasks + +The project uses [cargo-make](https://github.com/sagiegurari/cargo-make) to manage common development tasks. Here are the main tasks available: + + +```text +Build +---------- +build - No Description. +release-wasm - Build optimized wasm using CosmWasm optimizer and provide checksums +schema - No Description. +wasm - No Description. + +Chain Management +---------- +chain - Run the axoned CLI using the chain's home directory under a Docker container. +chain-add-keys - Add a set of predefined keys (recovered from the seed phrases) to the chain. +chain-init-folder - Initialize deploy folder to make sure scripts have the right permission (needed for linux) +chain-initialize - Initialize the chain with a validator's key and a set of predefined keys. ⚠️ The home directory is cleaned before. +chain-logs - Show the chain's container logs. +chain-start - Run the full node axoned application using the chain's home directory under a Docker container. +chain-stop - Stop the chain's container. + +Cleanup +---------- +clean - Clean all artifacts (cargo, docs, and chain). +clean-cargo - Clean cargo build artifacts. +clean-chain - Clean the chain data (⚠️ definitively). +clean-docs - Clean documentation folder. + +Code Quality +---------- +format - Format all files (Rust and TOML). +format-rust - Format rust sources files. (rustfmt provided by rust-toolchain.toml) +format-toml - Format toml file +lint - Check all linting (Rust, Cargo, and TOML). +lint-cargo - Check all Cargo linting (toml files and dependencies). +lint-cargo-deps - Check for unused dependencies. +lint-cargo-toml - Check lint of all Cargo.toml files. +lint-cargo-toml-file - Check lint of the given toml file +lint-rust - Check all Rust linting (formatting and clippy). +lint-rust-clippy - Check lint of all sources files (clippy via rust-toolchain.toml). +lint-rust-format - Check formatting and derives order (rustfmt via rust-toolchain.toml). +lint-toml - Check lint of all toml files. + +Contract Deployment +---------- +chain-deploy-contract - Deploy a specific contract to the chain. The contract must be compiled and the wasm file must be present in the artifacts directory (under target/wasm32-unknown-unknown/...). +chain-deploy-contracts - Deploy all the available contracts to the chain (under target/wasm32-unknown-unknown/...). +chain-inspect-contract - Inspect a specific contract deployed to the chain. +chain-list-contracts - List all the contracts deployed to the chain. + +Contract Interaction +---------- +chain-execute-contract - Execute a command on a specific contract to the chain. The contract must be already deployed and instantiated. +chain-instantiate-contract - Instantiate a specific contract to the chain. The contract must be already deployed. +chain-query-contract - Query a specific contract to the chain. The contract must be already deployed and instantiated. + +Development Tools +---------- +install - Install all required development tools. +install-cargo-hack - No Description. +install-cargo-machete - No Description. +install-cargo-sort-derives - No Description. +install-cargo-toml-lint - No Description. +install-cargo-workspaces - No Description. +install-cosmwasm-check - No Description. +install-cranky - No Description. +install-llvm-cov - No Description. +install-taplo-cli - No Description. + +Documentation +---------- +docs - Generate documentation +readme - Update README with help output + +Help +---------- +help - Display available tasks [aliases: default] + +Publishing +---------- +publish-crates - Publish all crates to the registry. Requires CARGO_REGISTRY_TOKEN to be set. + +Testing +---------- +test - Run all tests. +test-coverage - Run tests with coverage reporting. +test-unit - Run all unit tests. + +Verification +---------- +check - Check all requirements (prerequisites and contracts). +check-awk - Check awk is installed +check-contracts - Check WASM contracts validity. +check-jq - Check jq is installed (version 1.7 or higher, but below 2.0) +check-npx - Check npx is installed +check-perl - Check perl is installed +check-prerequisites - Check all the prerequisites are installed. +``` + + ### πŸ”§ Compiling Smart Contracts to Wasm To compile the Smart Contracts to Wasm, just invoke the `wasm` goal of the makefile: @@ -105,31 +207,6 @@ cargo make test-coverage ## πŸ“ Play with the Smart Contracts The project comes with a set of convenient tasks to manage the Smart Contracts and the blockchain. -To see the list of available tasks, run the following command: - -```sh -cargo make --list-all-steps | grep chain | sort | sed -r 's/chain(-?[a-zA-Z\-]*)/- `chain\1`/' -``` - -The list of available tasks for managing the chain is as follows: - -- `chain` - Run the axoned CLI using the chain's home directory under a Docker container. -- `chain-add-keys` - Add a set of predefined keys (recovered from the seed phrases) to the chain. -- `chain-clean` - Clean the chain data (⚠️ definitively) -- `chain-deploy-contract` - Deploy a specific contract to the chain. The contract must be compiled and the wasm file must be present in the artifacts directory (under target/wasm32-unknown-unknown/...). -- `chain-deploy-contracts` - Deploy all the available contracts to the chain (under target/wasm32-unknown-unknown/...). -- `chain-execute-contract` - Execute a command on a specific contract to the chain. The contract must be already deployed and instantiated. -- `chain-init-folder` - Initialize deploy folder to make sure scripts have the right permission (needed for linux) -- `chain-initialize` - Initialize the chain with a validator's key and a set of predefined keys. ⚠️ The home directory is cleaned before. -- `chain-inspect-contract` - Inspect a specific contract deployed to the chain. -- `chain-instantiate-contract` - Instantiate a specific contract to the chain. The contract must be already deployed. -- `chain-list-contracts` - List all the contracts deployed to the chain. -- `chain-logs` - Show the chain's container logs. -- `chain-query-contract` - Query a specific contract to the chain. The contract must be already deployed and instantiated. -- `chain-start` - Run the full node axoned application using the chain's home directory under a Docker container. -- `chain-stop` - Stop the chain's container. - -## πŸ’» Develop ### πŸš€ Initialize the chain @@ -226,7 +303,7 @@ Smart Contracts' schema. To generate the documentation follow the steps below. -### πŸ”¨ Pre-requisites +### πŸ”¨ Documentation Pre-requisites Be sure you have the following tools installed: @@ -244,7 +321,7 @@ To generate the documentation, just run: ```sh cargo make schema -cargo make docs-generate +cargo make docs ``` You'll find the generated documentation under the `docs` folder.