Devtools overhaul (#60)

Gives some much needed love to devtools:

- Adds git hooks
- Improves justfile tooling
- Adds additional CI checks

Author: MarcGuiselin

.envrc

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 watch_file \
+  justfile \
   rust-toolchain.toml \
   *.nix
 use flake

.githooks/pre-push

@@ -0,0 +1,48 @@
+#!/usr/bin/env sh
+set -eu
+
+required_rust_version="1.92.0"
+
+if ! command -v rustc >/dev/null 2>&1; then
+  echo "🚫 pre-push: rustc is not installed or not on PATH"
+  exit 1
+fi
+
+current_rust_version=$(rustc --version | awk '{print $2}')
+
+version_ge() {
+  awk -v v1="$1" -v v2="$2" '
+    BEGIN {
+      n1 = split(v1, a, ".")
+      n2 = split(v2, b, ".")
+      max = (n1 > n2 ? n1 : n2)
+
+      for (i = 1; i <= max; i++) {
+        x = (i <= n1 ? a[i] : 0) + 0
+        y = (i <= n2 ? b[i] : 0) + 0
+
+        if (x > y) exit 0
+        if (x < y) exit 1
+      }
+
+      exit 0
+    }
+  '
+}
+
+if ! version_ge "$current_rust_version" "$required_rust_version"; then
+  echo "🚫 pre-push: rustc $current_rust_version found, but $required_rust_version or newer is required"
+  exit 1
+fi
+
+echo "🔎 pre-push: running checks that mirror GitHub CI"
+echo "• cargo test"
+cargo test
+
+echo "• cargo clippy -- -D warnings"
+cargo clippy -- -D warnings
+
+echo "• cargo fmt --all -- --check"
+cargo fmt --all -- --check
+
+echo "✅ pre-push: all checks passed"

.github/workflows/ci.yaml

@@ -28,8 +28,8 @@ jobs:
             ~/.cargo/git/db/
             target/
           key: ${{ runner.os }}-cargo-test-${{ hashFiles('**/Cargo.toml') }}
-      - name: Install stable toolchain
-        uses: dtolnay/rust-toolchain@stable
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.92.0
       - name: Install Dependencies
         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev
       - name: Run cargo test
@@ -53,15 +53,40 @@ jobs:
             ~/.cargo/git/db/
             target/
           key: ${{ runner.os }}-cargo-clippy-${{ hashFiles('**/Cargo.toml') }}
-      - name: Install stable toolchain
-        uses: dtolnay/rust-toolchain@stable
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.92.0
         with:
           components: clippy
       - name: Install Dependencies
         run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev
       - name: Run clippy
         run: cargo clippy -- -D warnings
 
+  # Run cargo doc with rustdoc warnings denied
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/bin/
+            ~/.cargo/registry/index/
+            ~/.cargo/registry/cache/
+            ~/.cargo/git/db/
+            target/
+          key: ${{ runner.os }}-cargo-doc-${{ hashFiles('**/Cargo.toml') }}
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.92.0
+      - name: Install Dependencies
+        run: sudo apt-get update; sudo apt-get install --no-install-recommends libasound2-dev libudev-dev libwayland-dev
+      - name: Run cargo doc
+        run: RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace --all-features --exclude guest_wit_example --exclude host_wit_example --exclude simple
+
   # Run cargo fmt --all -- --check
   format:
     name: Format
@@ -70,8 +95,8 @@ jobs:
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
-      - name: Install stable toolchain
-        uses: dtolnay/rust-toolchain@stable
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@1.92.0
         with:
           components: rustfmt
       - name: Run cargo fmt

README.md

@@ -10,14 +10,14 @@
 [![Downloads](https://img.shields.io/crates/d/wasvy.svg)](https://crates.io/crates/wasvy)
 [![Docs](https://docs.rs/wasvy/badge.svg)](https://docs.rs/wasvy)
 [![Rust Version](https://img.shields.io/badge/rust-1.92.0+-blue.svg)](https://www.rust-lang.org)
-[![CI](https://github.com/wasvy-org/wasvy/workflows/CI/badge.svg)](https://github.com/wasvy-org/wasvy/actions)
+[![CI](https://github.com/wasvy-org/wasvy/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/wasvy-org/wasvy/actions)
 [![Discord](https://img.shields.io/discord/691052431525675048.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.com/channels/691052431525675048/1492230910383357992/1492230910383357992)
 
 > 🪺 **Just hatched**: This project in in the process of stabilization. Some features are still missing and breaking API changes are likely to happen as we approach a 1.0 release. Use at your own risk!
 
-> 🎯 **Community Feedback**: Your ideas, suggestions, and contributions are highly valued! Come and talk with us in the [Bevy Discord](https://discord.com/channels/691052431525675048/1034543904478998539). Report bugs and discuss new features on [Github](https://github.com/wasvy-org/wasvy/issues). Together, we can shape this into something great!
+> 🎯 **Community Feedback**: Your ideas, suggestions, and contributions are highly valued! Come and talk with us in the [Bevy Discord](https://discord.com/channels/691052431525675048/1492230910383357992/1492230910383357992). Report bugs and discuss new features on [Github](https://github.com/wasvy-org/wasvy/issues). Together, we can shape this into something great!
 
-> 💡 **TIP**: Check out the [`justfile`](justfile) for useful commands and as a reference for common operations in the project.
+> 💡 **TIP**: Check out the [`justfile`](./justfile) for useful commands and as a reference for common operations in the project.
 
 ## Overview
 
@@ -232,6 +232,30 @@ Check out the examples directory for more detailed usage:
 
 Contributions come in many forms, and we welcome all kinds of help! Here's how you can contribute:
 
+### Setup your development environment
+
+Using the project's [Nix flake](https://nixos.org/download/) is the simplest way to get a working development environment.
+
+1. Install [Nix](https://nixos.org/download/).
+2. Install [direnv](https://direnv.net/) and hook it into your shell by following the [official setup instructions](https://direnv.net/docs/hook.html).
+3. From the repository root, allow direnv to load the flake-based development shell:
+
+```sh
+direnv allow
+```
+
+Once allowed, direnv will automatically enter the development shell for this repository and provision the required tooling.
+
+### Other environments
+
+If you are not using Nix, install the required tooling manually:
+
+- Install [Rust 1.92.0+](https://www.rust-lang.org/tools/install)
+- Install [`just`](https://github.com/casey/just)
+- Run `just enable-git-hooks`
+
+For additional project commands, see the [`justfile`](./justfile).
+
 ### Code Contributions
 
 1. Fork the repository

crates/wasvy_cli/src/runtime.rs

@@ -17,7 +17,7 @@ use crate::{
 
 /// The config for a [Runtime]
 ///
-/// Create a new runtime by calling [Runtime::build]
+/// Create a new runtime by calling [Runtime::new]
 pub struct Config {
     /// A namespace, usually the name of the game/software being modded
     pub namespace: String,

flake.nix

@@ -44,6 +44,7 @@
           wkg
           nixd
           nil
+          ripgrep
 
           poetry
           python3
@@ -80,6 +81,8 @@
           shellHook = ''
             ${wkgConfigHook}
 
+            just enable-git-hooks
+
             # Impure python setup for now
             unset PYTHONPATH
             uv sync --directory examples/python_example

justfile

@@ -1,34 +1,107 @@
+# TIP: run the command `just -l` to get an overview
+
+# Build an example rust crate to Wasm and copy it into host assets.
+[group("examples")]
+[arg("example", pattern="^(simple|guest_wit_example)$")]
 build-example example:
 	cargo build --release --target wasm32-wasip2 -p {{example}}
 	mkdir -p ./examples/host_example/assets/mods
 	cp ./target/wasm32-wasip2/release/{{example}}.wasm ./examples/host_example/assets/mods
 
+# Run the host example app.
+[group("examples")]
 run-host-example:
 	cargo run -p host_example --features bevy/file_watcher
 
-# Requires `poetry` to run
+# Run the host wit example app.
+[group("examples")]
+run-host-wit-example:
+	cargo run -p host_example --features bevy/file_watcher
+
+# Build the Python example mod.
+[group("examples")]
+[working-directory("examples/python_example/src")]
 build-example-python:
-	cd examples/python_example/src && poetry run componentize-py --wit-path ../wit/ --world example componentize app -o ../../host_example/assets/mods/python.wasm
+	poetry run componentize-py --wit-path ../wit/ --world example componentize app -o ../../host_example/assets/mods/python.wasm
 
-# Create the bindings for the python example
+# Generate Python bindings for example mod.
+[group("examples")]
+[working-directory("examples/python_example")]
 example-bindings-python:
-	cd examples/python_example && rm -rf ./src/componentize_py_async_support && rm -rf ./src/wit_world && rm -rf ./src/componentize_py_runtime.pyi && rm -rf ./src/componentize_py_types.py && rm -rf ./src/poll_loop.py && poetry run componentize-py --wit-path wit/ --world example bindings src
+	rm -rf ./src/componentize_py_async_support
+	rm -rf ./src/wit_world
+	rm -f ./src/componentize_py_runtime.pyi
+	rm -f ./src/componentize_py_types.py
+	rm -f ./src/poll_loop.py
+	poetry run componentize-py --wit-path wit/ --world example bindings src
 
+# Build the Go example mod.
+[group("examples")]
+[working-directory("examples/go_example/src")]
+[env("GOARCH", "wasm")]
+[env("GOOS", "wasip1")]
 build-example-go:
-	cd examples/go_example/src && GOARCH="wasm" GOOS="wasip1" go build -o core.wasm -buildmode=c-shared -ldflags=-checklinkname=0 && wasm-tools component embed -w example ../wit/ core.wasm -o core-with-wit.wasm && wasm-tools component new --adapt ../wasi_snapshot_preview1.reactor.wasm core-with-wit.wasm -o go.wasm
+	go build -o core.wasm -buildmode=c-shared -ldflags=-checklinkname=0
+	wasm-tools component embed -w example ../wit/ core.wasm -o core-with-wit.wasm
+	wasm-tools component new --adapt ../wasi_snapshot_preview1.reactor.wasm core-with-wit.wasm -o go.wasm
 
+# Generate Go bindings for example mod.
+[group("examples")]
+[working-directory("examples/go_example/src")]
 example-bindings-go:
-	cd examples/go_example/src && wit-bindgen go -w example ../wit/
+	wit-bindgen go -w example ../wit/
 
-# For the fetching to take effect you must delete the deps folder manually
+# Fetch WIT dependencies for one example (deprecated, use cli instead).
+[group("examples")]
 example-fetch-deps example:
 	cd examples/{{example}} && wkg wit fetch
 
-build-host:
-	cargo build -p wasvy
+# Enable repository git hooks.
+[group("setup")]
+enable-git-hooks:
+	git config core.hooksPath .githooks
+	chmod +x .githooks/pre-push
 
+# Build the ECS WIT package.
+[group("chores")]
 build-wasvy-ecs:
 	wkg wit build --wit-dir ./wit/ecs/
 
+# Publish the ECS package to wa.dev.
+[group("chores")]
 publish-wasvy-ecs file_path version:
 	wkg publish --package wasvy:ecs@{{version}} {{file_path}} --registry wa.dev
+
+# Replace the existing (1.92.0) rust toolchain version with a new one.
+[group("chores")]
+[arg("new", pattern="^\\d+\\.\\d+\\.\\d+$")]
+bump-toolchain new:
+	rg -l 'rust' . | xargs sed -i "/rust/s/1.92.0/{{new}}/g"
+
+# Replace the existing (0.18.0) bevy version with a new one.
+[group("chores")]
+[arg("new", pattern="^\\d+\\.\\d+\\.\\d+$")]
+bump-bevy new:
+	rg -l -g '!Cargo.lock' 'bevy' . | xargs sed -i "/bevy/s/0.18.0/{{new}}/g"
+	cargo check
+
+# Replace the existing (0.0.8) wasvy version with a new one.
+[group("chores")]
+[arg("new", pattern="^\\d+\\.\\d+\\.\\d+$")]
+bump-version new:
+	rg -l -g '!Cargo.lock' 'version' . | xargs sed -i "/version/s/0.0.8/{{new}}/g"
+	cargo check
+
+# Publishes all crates
+[group("chores")]
+[confirm]
+publish:
+	# CI
+	cargo test
+	cargo clippy -- -D warnings
+	cargo fmt --all -- --check
+	RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --workspace --all-features --exclude guest_wit_example --exclude host_wit_example --exclude simple
+
+	# Publish
+	cargo publish -p wasvy_macros
+	cargo publish -p wasvy

rust-toolchain.toml

@@ -1,5 +1,5 @@
 [toolchain]
-channel = "1.92.0" # Track same version as Bevy
+channel = "1.92.0" # Track same rust version as Bevy
 components = [
     "cargo",
     "llvm-tools",

src/authoring.rs

@@ -5,7 +5,7 @@
 //!   **no methods**. This is important for components that are queried or
 //!   serialized but never invoked.
 //! - [`WasvyMethods`] registers exported methods (typically via
-//!   [`#[wasvy::methods]`](crate::methods)).
+//!   [`#[wasvy::methods]`](macro@crate::methods)).
 //! - [`WasvyAutoRegistrationPlugin`] apply all submitted
 //!   registrations to a Bevy `App`.
 //!

src/component.rs

@@ -23,7 +23,7 @@ pub type TypePath = String;
 
 /// Registry for storing the components that are registered from WASM assets.
 ///
-/// Note that this is unique per world, not per app like the [AppTypeRegistry](bevy_ecs::reflect::AppTypeRegistry)
+/// Note that this is unique per world, not per app like the [AppTypeRegistry]
 #[derive(Default, Clone, Debug, Resource, Deref, DerefMut)]
 pub struct WasmComponentRegistry(HashMap<TypePath, ComponentId>);