Major Refactor/Rewrite

.github/workflows/ci.yaml

@@ -54,15 +54,15 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v3
 
-      - name: Setup Rust with rustfmt
+      - name: Setup Rust (nightly) with rustfmt
         uses: actions-rust-lang/setup-rust-toolchain@v1
         with:
-          toolchain: stable
+          toolchain: nightly
           components: rustfmt
           override: true
 
-      - name: Run rustfmt
-        run: cargo +stable fmt --all -- --check
+      - name: Run rustfmt (nightly)
+        run: cargo +nightly fmt --all -- --check
 
   clippy:
     runs-on: ubuntu-latest

ARCHITECTURE.md

@@ -0,0 +1,84 @@
+# Architecture
+
+This document explains how the `bevy_auto_plugin` ecosystem is structured and how macro expansion flows through the crates.
+
+## High-Level Flow
+
+1. **User-facing macros** are re-exported from `bevy_auto_plugin` (in [`src/lib.rs`](src/lib.rs) under the `prelude`).
+2. When a user applies:
+    - `#[derive(AutoPlugin)]` → expansion handled by  
+      [`bevy_auto_plugin_shared/src/__private/expand/derive/auto_plugin.rs`](crates/bevy_auto_plugin_shared/src/__private/expand/derive/auto_plugin.rs)
+    - `#[auto_plugin]` (attribute form) → expansion handled by  
+      [`bevy_auto_plugin_shared/src/__private/expand/attr/auto_plugin.rs`](crates/bevy_auto_plugin_shared/src/__private/expand/attr/auto_plugin.rs)
+    - `#[auto_*( ... )]` attributes → routed to  
+      [`bevy_auto_plugin_shared/src/__private/expand/attr/`](crates/bevy_auto_plugin_shared/src/__private/expand/attr/)
+
+---
+
+## Attribute Types
+
+`auto_*` attributes fall into two categories:
+
+### Actions
+
+- Mutate the input token stream **and/or** append code that registers static slices used during plugin initialization.
+- Parsing types are defined in:  
+  [`bevy_auto_plugin_shared/src/macro_api/attributes/actions`](crates/bevy_auto_plugin_shared/src/macro_api/attributes/actions)
+
+Each action attribute is modeled as: `ItemAttribute<Composed<T, P, G>, R>`
+
+Where:
+
+| Generic | Meaning |
+|---------|----------|
+| `T` | The [`darling`](https://crates.io/crates/darling) parameter struct for the attribute |
+| `P` | Plugin context: `WithPlugin` |
+| `G` | Generics handling: `WithZeroGenerics`, `WithZeroOrSingleGenerics`, or `WithZeroOrManyGenerics` |
+| `R` | Resolver restricting usage: `AllowAny`, `AllowFn`, or `AllowStructOrEnum` |
+
+notes:
+- `Composed` can probably be merged into `ItemAttribute` but it's currently left open if we decide to add macros that aren't attached to the usual items (unlikely).
+
+Actions can implement traits for one or both of the following wrapper types:
+
+#### [`AppMutationEmitter<T>`](crates/bevy_auto_plugin_shared/src/macro_api/emitters/app_mutation.rs)
+
+- Generates tokens for static slice registration and plugin mutation.
+- **May also mutate the input tokens** (rare).  
+  Example use case: allowing helper attributes on enum variants.  
+  See:  
+  [`bevy_auto_plugin_shared/src/macro_api/attributes/actions/auto_configure_system_set.rs`](crates/bevy_auto_plugin_shared/src/macro_api/attributes/actions/auto_configure_system_set.rs)
+
+#### [`AttrEmitter<T>`](crates/bevy_auto_plugin_shared/src/macro_api/emitters/attr.rs)
+
+- Responsible for serializing a parsed parameter struct back into attribute tokens (useful for rewrite expansions).
+
+---
+
+### Rewrites
+
+- Expand into one or more other attributes.
+- Only modify the **item’s attributes**, not the item body.
+- Uses wrapper type [`AttrExpansionEmitter<T>`](crates/bevy_auto_plugin_shared/src/macro_api/emitters/attr_expansion.rs)
+
+---
+
+## Supporting Infrastructure
+
+### Custom Parsing
+
+Located in:  
+[`bevy_auto_plugin_shared/src/syntax/ast`](crates/bevy_auto_plugin_shared/src/syntax/ast)  
+Includes custom AST fragments, parsing helpers, and type definitions used across attributes.
+
+### Codegen Tokens
+
+All hygienic Bevy paths are centralized in:  
+[`bevy_auto_plugin_shared/src/codegen/tokens.rs`](crates/bevy_auto_plugin_shared/src/codegen/tokens.rs)
+
+- Crate alias resolution is handled via [`proc-macro-crate`](https://crates.io/crates/proc-macro-crate).
+
+### Token Preservation
+
+Macro expansions are designed to **preserve input tokens on errors**.  
+This ensures IDEs (like rust-analyzer) maintain valid syntax trees and prevent code “going red” on partially-written macro usage.

Cargo.toml

@@ -6,7 +6,6 @@ repository = "https://github.com/StrikeForceZero/bevy_auto_plugin"
 license = "MIT OR Apache-2.0"
 description = "Procedural attribute macros for Bevy apps that reduce boilerplate by automatically registering components, resources, events, states, and systems in your plugin's build function."
 edition = "2024"
-rust-version = "1.88"
 publish = true
 
 [features]
@@ -79,6 +78,7 @@ log = { workspace = true }
 wasm-bindgen-test = { workspace = true }
 internal_test_util = { workspace = true }
 internal_test_proc_macro = { workspace = true }
+meta_merge = "0.1.1"
 
 [build-dependencies]
 rustc_version = "0.4"

build.rs

@@ -1,4 +1,7 @@
-use rustc_version::{Channel, version_meta};
+use rustc_version::{
+    Channel,
+    version_meta,
+};
 
 fn main() {
     println!("cargo:rustc-check-cfg=cfg(nightly)");

crates/bevy_auto_plugin_proc_macros/Cargo.toml

@@ -18,13 +18,4 @@ log_plugin_build = ["bevy_auto_plugin_shared/log_plugin_build"]
 
 [dependencies]
 bevy_auto_plugin_shared = { workspace = true }
-syn = { workspace = true }
-proc-macro2 = { workspace = true }
-quote = { workspace = true }
-darling = { workspace = true }
-
-[dev-dependencies]
-# needed for doc-tests
-bevy = { workspace = true }
-bevy_app = { workspace = true }
-bevy_auto_plugin = { path = "../../.", default-features = false }
+proc-macro2 = { workspace = true }

crates/bevy_auto_plugin_proc_macros/src/lib.rs

@@ -2,8 +2,7 @@ use bevy_auto_plugin_shared::__private::expand;
 use proc_macro::TokenStream as CompilerStream;
 use proc_macro2::TokenStream as MacroStream;
 
-#[allow(dead_code)]
-/// thin adapter converting between the compiler-level and proc_macro2 streams
+/// Thin adapter converting between the compiler-level and proc_macro2 streams
 fn handle_attribute<F: Fn(MacroStream, MacroStream) -> MacroStream>(
     handler: F,
     attr: CompilerStream,
@@ -12,168 +11,147 @@ fn handle_attribute<F: Fn(MacroStream, MacroStream) -> MacroStream>(
     handler(attr.into(), input.into()).into()
 }
 
-/// Derives `AutoPlugin` which generates the initialization function that automatically registering types, events, and resources in the `App`.
-#[doc = include_str!("../docs/proc_attributes/derive_auto_plugin.md")]
+/// Derives `AutoPlugin`, which generates the initialization function that automatically registers types, events, resources, system, ..., etc. in the `App`.
 #[proc_macro_derive(AutoPlugin, attributes(auto_plugin))]
 pub fn derive_auto_plugin(input: CompilerStream) -> CompilerStream {
     expand::derive::auto_plugin::expand_derive_auto_plugin(input.into()).into()
 }
 
-/// Attaches to a fn and injects a call to the initialization function that automatically registering types, events, and resources in the `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_plugin.md")]
+/// Attaches to an `fn` and injects a call to the `AutoPlugin` initialization function that automatically registers types, events, resources, system, ..., etc. in the `App`.
 #[allow(unused_variables, unused_mut, unreachable_code)]
 #[proc_macro_attribute]
 pub fn auto_plugin(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_plugin::expand_auto_plugin, attr, input)
 }
 
-/// Automatically registers a type with the Bevy `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_register_type.md")]
+/// Automatically registers item deriving `Reflect` in `TypeRegistry` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_register_type(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_register_type, attr, input)
 }
 
-/// Automatically adds a message type to the Bevy `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_add_message.md")]
+/// Automatically adds a `Message` to the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_add_message(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_add_message, attr, input)
 }
 
-/// Automatically configures a `SystemSet`.
-#[doc = include_str!("../docs/proc_attributes/auto_configure_system_set.md")]
+/// Automatically configures a `SystemSet` in the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_configure_system_set(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_configure_system_set, attr, input)
 }
 
-/// Automatically inserts a resource in the Bevy `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_init_resource.md")]
+/// Automatically initializes a `Resource` in the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_init_resource(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_init_resource, attr, input)
 }
 
-/// Automatically inserts a resource in the Bevy `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_insert_resource.md")]
+/// Automatically inserts a `Resource` in the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_insert_resource(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_insert_resource, attr, input)
 }
 
-/// Automatically initializes a State in the Bevy `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_init_state.md")]
+/// Automatically initializes a `State` in the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_init_state(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_init_state, attr, input)
 }
 
-/// Automatically initializes a SubState in the Bevy `App`.
-#[doc = include_str!("../docs/proc_attributes/auto_init_sub_state.md")]
+/// Automatically initializes a `SubState` in the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_init_sub_state(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_init_sub_state, attr, input)
 }
 
 /// Automatically registers a required component `Name` with a value using the concrete name of the item.
-#[doc = include_str!("../docs/proc_attributes/auto_name.md")]
 #[proc_macro_attribute]
 pub fn auto_name(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_name, attr, input)
 }
 
-/// Automatically registers item as States for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_register_state_type.md")]
+/// Automatically registers item representing `States` in `TypeRegistry` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_register_state_type(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_register_state_type, attr, input)
 }
 
-/// Automatically adds the fn as a system for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_add_system.md")]
+/// Automatically adds the `fn` as a `System` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_add_system(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_add_system, attr, input)
 }
 
-/// Automatically adds the fn as a proc_attributes observer to bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_add_observer.md")]
+/// Automatically adds the `fn` as a `Observer` to the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_add_observer(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_add_observer, attr, input)
 }
 
-/// Automatically adds the plugin as a sub-plugin to bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_add_system.md")]
+/// Automatically adds the `Plugin` as a sub-plugin to the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_add_plugin(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_add_plugin, attr, input)
 }
 
-/// Automatically registers item as Component for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_component.md")]
+/// Automatically registers item as `Component` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_component(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_component, attr, input)
 }
 
-/// Automatically registers item as Resource for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_resource.md")]
+/// Automatically registers item as `Resource` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_resource(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_resource, attr, input)
 }
 
-/// Automatically registers item as Event for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_event.md")]
+/// Automatically registers item as `Event` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_event(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_event, attr, input)
 }
 
-/// Automatically registers item as Message for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_message.md")]
+/// Automatically registers item as `Message` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_message(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_message, attr, input)
 }
 
-/// Automatically registers item as States for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_states.md")]
+/// Automatically registers item as `States` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_states(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_states, attr, input)
 }
 
-/// Automatically adds the fn as a system for bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_system.md")]
+/// Automatically registers item as `SubStates` for the Bevy `App`.
+#[proc_macro_attribute]
+pub fn auto_sub_states(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
+    handle_attribute(expand::attr::auto_sub_states, attr, input)
+}
+
+/// Automatically adds the `fn` as a `System` for the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_system(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_system, attr, input)
 }
 
-/// Automatically adds proc_attributes observer to bevy app. (See below for additional options)
-#[doc = include_str!("../docs/proc_attributes/auto_observer.md")]
+/// Automatically adds `Observer` to the Bevy `App`.
 #[proc_macro_attribute]
 pub fn auto_observer(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_observer, attr, input)
 }
 
-/// Automatically binds `plugin = _` to every auto_* attribute below it
-#[doc = include_str!("../docs/proc_attributes/auto_run_on_build.md")]
+/// Automatically runs the `fn` on build.
 #[proc_macro_attribute]
 pub fn auto_run_on_build(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
     handle_attribute(expand::attr::auto_run_on_build, attr, input)
 }
 
 /// Automatically binds `plugin = _` to every auto_* attribute below it
-#[doc = include_str!("../docs/proc_attributes/auto_bind_plugin.md")]
 #[proc_macro_attribute]
 pub fn auto_bind_plugin(attr: CompilerStream, input: CompilerStream) -> CompilerStream {
-    handle_attribute(
-        expand::attr::auto_bind_plugin::auto_bind_plugin_outer,
-        attr,
-        input,
-    )
+    handle_attribute(expand::attr::auto_bind_plugin::auto_bind_plugin_outer, attr, input)
 }