test: fuzz testing with cargo-fuzz

Cargo.toml

@@ -4,14 +4,15 @@ lto = "thin"
 [workspace]
 resolver = "2"
 members = [
-    "hugr",
-    "hugr-core",
-    "hugr-passes",
-    "hugr-cli",
-    "hugr-model",
-    "hugr-llvm",
-    "hugr-py",
-    "hugr-persistent",
+  "hugr",
+  "hugr-core",
+  "hugr-passes",
+  "hugr-cli",
+  "hugr-model",
+  "hugr-llvm",
+  "hugr-py",
+  "hugr-persistent",
+  "fuzz",
 ]
 default-members = ["hugr", "hugr-core", "hugr-passes", "hugr-cli", "hugr-model"]
 
@@ -25,10 +26,10 @@ license = "Apache-2.0"
 
 [workspace.lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = [
-    # Set by our CI
-    'cfg(ci_run)',
-    # Set by codecov
-    'cfg(coverage,coverage_nightly)',
+  # Set by our CI
+  'cfg(ci_run)',
+  # Set by codecov
+  'cfg(coverage,coverage_nightly)',
 ] }
 
 missing_docs = "warn"

devenv.lock

@@ -51,31 +51,10 @@
         "type": "github"
       }
     },
-    "git-hooks": {
-      "inputs": {
-        "flake-compat": "flake-compat",
-        "gitignore": "gitignore",
-        "nixpkgs": [
-          "nixpkgs"
-        ]
-      },
-      "locked": {
-        "lastModified": 1747372754,
-        "owner": "cachix",
-        "repo": "git-hooks.nix",
-        "rev": "80479b6ec16fefd9c1db3ea13aeb038c60530f46",
-        "type": "github"
-      },
-      "original": {
-        "owner": "cachix",
-        "repo": "git-hooks.nix",
-        "type": "github"
-      }
-    },
     "gitignore": {
       "inputs": {
         "nixpkgs": [
-          "git-hooks",
+          "pre-commit-hooks",
           "nixpkgs"
         ]
       },
@@ -107,15 +86,33 @@
         "type": "github"
       }
     },
+    "pre-commit-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1747372754,
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "rev": "80479b6ec16fefd9c1db3ea13aeb038c60530f46",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
         "devenv": "devenv",
         "fenix": "fenix",
-        "git-hooks": "git-hooks",
         "nixpkgs": "nixpkgs",
-        "pre-commit-hooks": [
-          "git-hooks"
-        ]
+        "pre-commit-hooks": "pre-commit-hooks"
       }
     },
     "rust-analyzer-src": {

devenv.nix

@@ -48,7 +48,7 @@ in
     # https://devenv.sh/languages/
     # https://devenv.sh/reference/options/#languagesrustversion
     languages.rust = {
-      channel = "stable";
+      channel = "nightly";
       enable = true;
       components = [ "rustc" "cargo" "clippy" "rustfmt" "rust-analyzer" ];
     };

fuzz/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "fuzz"
+version = "0.0.0"
+publish = false
+edition = "2024"
+
+[package.metadata]
+cargo-fuzz = true
+
+[dependencies]
+libfuzzer-sys = "0.4"
+hugr-model = { path = "../hugr-model/", features = ["arbitrary"] }
+
+# [dependencies.hugr]
+# path = ".."
+
+[[bin]]
+name = "fuzz_random"
+path = "fuzz_targets/fuzz_random.rs"
+test = false
+doc = false
+bench = false
+
+[[bin]]
+name = "fuzz_structure"
+path = "fuzz_targets/fuzz_structure.rs"
+test = false
+doc = false
+bench = false

fuzz/README.md

@@ -0,0 +1,64 @@
+# Fuzz testing
+
+This project uses `cargo-fuzz` for doing fuzz testing for hugr.
+
+## Requisites
+
+1. Install `cargo-fuzz` with: `cargo install cargo-fuzz`
+2. Build with `cargo fuzz build`
+
+> [!NOTE]
+> The `libFuzzer` used by `cargo-fuzz` needs **nightly**.
+
+## Fuzz targets
+
+You can list the fuzzing targets with:
+`cargo fuzz list`
+
+### Model: Random
+
+The [fuzz_random](./fuzz_targets/fuzz_random.rs) target uses the coverage-guided
+`libFuzzer` fuzzing engine to generate random bytes that we then try to
+convert to a package with `hugr_model::v0::ast::Package::from_str()`.
+
+To run this target:
+`cargo fuzz run fuzz_random`
+
+It is recommended to provide the `libFuzzer` with a corpus to speed up the
+generation of test inputs. For this we can use the fixtures in
+`hugr/hugr-model/tests/fixtures`:
+`cargo fuzz run fuzz_random ../hugr-model/tests/fixtures`
+
+If you want `libFuzzer` to mutate the examples with ascii characters only:
+`cargo fuzz run fuzz_random -- -only_ascii=1`
+
+### Model: Structure
+
+The [fuzz_structure](./fuzz_targets/fuzz_structure.rs) target uses `libFuzzer` to do
+[structure-aware](https://rust-fuzz.github.io/book/cargo-fuzz/structure-aware-fuzzing.html)
+modifications of the `hugr_model::v0::ast::Package` and its members.
+
+To run this target:
+`cargo fuzz run fuzz_structure`
+
+> [!NOTE]
+> This target needs some slight modifications to the `hugr-model` source
+> code so the structs and enums can derive the `Arbitrary` implementations
+> needed by `libFuzzer`.
+> The `arbitrary` features for `ordered-float` and `smol_str` are also needed.
+
+## Results
+
+The fuzzing process will be terminated once a crash is detected, and the offending input
+will be saved to the `artifacts/<target>` directory. You can reproduce the crash by doing:
+`cargo fuzz run fuzz_structure artifacts/<target>/crash-XXXXXX`
+
+If you want to keep the fuzzing process, even after a crash has been detected,
+you can provide the options `-fork=1` and `-ignore_crashes=1`.
+
+## Providing options to `libFuzzer`
+
+You can provide lots of options to `libFuzzer` by doing `cargo fuzz run <target> -- -flag1=val1 -flag2=val2`.
+
+To see all the available options:
+`cargo fuzz run <target> -- -help=1`

fuzz/fuzz_targets/fuzz_random.rs

@@ -0,0 +1,11 @@
+#![no_main]
+
+use libfuzzer_sys::fuzz_target;
+use hugr_model::v0 as model;
+use std::str::FromStr;
+
+fuzz_target!(|data: &[u8]| {
+    if let Ok(s) = std::str::from_utf8(data) {
+        let _package_ast = model::ast::Package::from_str(&s);
+    }
+});

fuzz/fuzz_targets/fuzz_structure.rs

@@ -0,0 +1,14 @@
+#![no_main]
+
+use hugr_model::v0 as model;
+use libfuzzer_sys::fuzz_target;
+use model::bumpalo::Bump;
+use hugr_model::v0::ast::Package;
+
+fuzz_target!(|package: Package| {
+    let bump = Bump::new();
+    let package = package.resolve(&bump).unwrap();
+    let bytes = model::binary::write_to_vec(&package);
+    let deserialized_package = model::binary::read_from_slice(&bytes, &bump).unwrap();
+    assert_eq!(package, deserialized_package);
+});

hugr-model/Cargo.toml

@@ -23,13 +23,14 @@ derive_more = { workspace = true, features = ["display", "error", "from"] }
 fxhash.workspace = true
 indexmap.workspace = true
 itertools.workspace = true
-ordered-float = { workspace = true }
+ordered-float = { workspace = true, features = ["arbitrary"] }
 pest = { workspace = true }
 pest_derive = { workspace = true }
 pretty = { workspace = true }
-smol_str = { workspace = true, features = ["serde"] }
+smol_str = { workspace = true, features = ["serde", "arbitrary"] }
 thiserror.workspace = true
 pyo3 = { workspace = true, optional = true, features = ["extension-module"] }
+arbitrary = { version = "1", optional = true, features = ["derive"] }
 
 [features]
 pyo3 = ["dep:pyo3"]