Derive macro for Arbitrary

Author: flyingmutant

Cargo.lock

@@ -1,5 +1,5 @@
 [workspace]
-members = ["chaos_theory", "chaos_theory_core", "chaos_theory_v2", "xtask"]
+members = ["chaos_theory", "chaos_theory_core", "chaos_theory_derive", "chaos_theory_v2", "xtask"]
 exclude = ["chaos_theory_example", "chaos_theory_example_fuzz"]
 resolver = "2"
 
@@ -65,9 +65,14 @@ indexmap = "2.11.4"
 libfuzzer-sys = "0.4.12"
 log = "0.4.27"
 ordered-float = "5.1.0"
+prettyplease = "0.2"
+proc-macro2 = "1.0"
+quote = "1.0"
 regex = "1.11.1"
 regex-syntax = "0.8.5"
+syn = { version = "2.0", default-features = false }
 tinyvec = "1.10.0"
 xshell = "0.2.6"
 
 chaos_theory_core = { path = "chaos_theory_core" }
+chaos_theory_derive = { version = "0.2.2", path = "chaos_theory_derive" }

Cargo.toml

@@ -43,7 +43,7 @@ you can use to reproduce the case.
   - structural mutations and crossover
   - example-guided generation
   - built-in swarm testing
-- Macro-free, imperative API
+- Macro-free, imperative API (with optional derive macro for `Arbitrary`)
 - Zero unsafe code and zero required dependencies
 
 ## Documentation
@@ -55,7 +55,6 @@ https://docs.rs/chaos_theory
 Beta – chaos_theory works well and is useful, but does not guarantee API stability.
 
 Notable gaps:
-- Derive macro for `Arbitrary`
 - Proper recursive generators
 
 ## Contributing

README.md

@@ -23,7 +23,8 @@ workspace = true
 
 [features]
 # default = ["nightly"]
-all = ["ecow", "hashbrown", "indexmap", "ordered_float", "regex", "tinyvec"]
+all = ["derive", "ecow", "hashbrown", "indexmap", "ordered_float", "regex", "tinyvec"]
+derive = ["dep:chaos_theory_derive"]
 ecow = ["dep:ecow"]
 hashbrown = ["dep:hashbrown"]
 indexmap = ["dep:indexmap"]
@@ -35,6 +36,7 @@ nightly = ["_bench"]
 _bench = []
 
 [dependencies]
+chaos_theory_derive = { workspace = true, optional = true }
 ecow = { workspace = true, optional = true }
 hashbrown = { workspace = true, optional = true }
 indexmap = { workspace = true, optional = true }

chaos_theory/Cargo.toml

@@ -31,5 +31,4 @@
 
 ## features
 
-- derive macro
 - consider saving failures, at least temporarily

chaos_theory/TODO.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## Unreleased
+
+- Add optional `derive` feature with `#[derive(chaos_theory::Arbitrary)]` support.
+
 ## 0.2.2 (2026-02-23)
 
 - Make FAQ link to API items.

chaos_theory/docs/CHANGELOG.md

@@ -22,7 +22,7 @@ chaos_theory is built around simple macro-free imperative API, has fuzzing suppo
 and cool tricks like built-in swarm testing and example-based data generation.
 
 `proptest` is more mature and feature‑rich; chaos_theory is newer and currently
-lacks important features like derive macro and recursion helpers.
+lacks some important features like recursion helpers.
 
 ## How is it different from `arbitrary` plus `libfuzzer_sys`?
 

chaos_theory/docs/FAQ.md

@@ -234,15 +234,40 @@ let city = make::string_matching("[A-Za-z '-]+", true).seeded(&cities, true);
 Built-in generators already have seeds pre-configured internally, so use [`seeded`][generator_seeded]
 only to provide seeds that are specific to your domain.
 
+### Deriving `Arbitrary`
+
+For most domain types, prefer derive instead of hand-writing generators.
+
+Enable derive support:
+
+```toml
+[dev-dependencies]
+chaos_theory = { version = "0.3", features = ["derive"] }
+```
+
+Then derive:
+
+```rust
+# #[cfg(feature = "derive")]
+#[derive(Debug, chaos_theory::Arbitrary)]
+struct Point {
+    x: i32,
+    y: i32,
+}
+```
+
+Derive-generated implementations follow the same rules as hand-written ones:
+variant choices are structural (`select`) and `example` is threaded through fields.
+
 ### Writing Custom Generators
 
 There are two main approaches:
 
 - Use [`make::from_fn`][make_from_fn] for small generators
 - Implement [`Generator`][generator] directly for full control
 
-Most of this becomes unnecessary once a derive macro for [`Arbitrary`][arbitrary] exists, but
-it is still useful for domain-specific logic.
+With derive support for [`Arbitrary`][arbitrary], most of this is unnecessary for plain data
+models, but it is still useful for domain-specific logic.
 
 #### Struct-Like Types
 

chaos_theory/docs/guide.md

@@ -48,7 +48,7 @@ you can use to reproduce the case.
   - structural mutations and crossover
   - example-guided generation
   - built-in swarm testing
-- Macro-free, imperative API
+- Macro-free, imperative API (with optional derive macro for [`Arbitrary`])
 - Zero unsafe code and zero required dependencies
 
 # Documentation
@@ -65,6 +65,9 @@ extern crate alloc;
 #[cfg(all(test, feature = "_bench"))]
 extern crate test;
 
+#[cfg(feature = "derive")]
+pub use chaos_theory_derive::Arbitrary;
+
 use std::path::Path;
 
 mod base64;

chaos_theory/src/lib.rs

@@ -0,0 +1,34 @@
+// Copyright 2026 Gregory Petrosyan <pgregory@pgregory.net>
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+//! Integration tests for `#[derive(chaos_theory::Arbitrary)]`.
+
+#![cfg(feature = "derive")]
+
+use chaos_theory::{Arbitrary, Source, check};
+
+include!("../../testdata/derive_cases.rs");
+
+fn assert_reconstruct<T>(src: &mut Source, example_label: &str, value_label: &str)
+where
+    T: chaos_theory::Arbitrary + core::fmt::Debug + PartialEq,
+{
+    let example: T = src.any(example_label);
+    let value = src.as_raw().any(value_label, Some(&example));
+    assert_eq!(value, example);
+}
+
+#[test]
+fn derive_reconstructs_examples() {
+    check(|src| {
+        assert_reconstruct::<Point>(src, "point_example", "point_value");
+        assert_reconstruct::<Triple>(src, "triple_example", "triple_value");
+        assert_reconstruct::<Marker>(src, "marker_example", "marker_value");
+        assert_reconstruct::<Imported>(src, "imported_example", "imported_value");
+        assert_reconstruct::<Wrapper<u16>>(src, "wrapper_example", "wrapper_value");
+        assert_reconstruct::<Action<u8>>(src, "action_example", "action_value");
+    });
+}