reinhardt_macros/

lib.rs

//! # Reinhardt Procedural Macros
//!
//! Provides Django-style decorators as Rust procedural macros.
//!
//! ## Macros
//!
//! - `#[routes]` - Register URL pattern function for automatic discovery
//! - `#[api_view]` - Convert function to API view
//! - `#[action]` - Define custom ViewSet action
//! - `#[get]`, `#[post]`, etc. - HTTP method decorators
//! - `#[permission_required]` - Permission decorator
//!

#![warn(missing_docs)]

use proc_macro::TokenStream;
use syn::{ItemFn, ItemStruct, parse_macro_input};

mod action;
mod admin;
mod api_view;
mod app_config_attribute;
mod app_config_derive;
mod apply_update_attribute;
mod apply_update_derive;
mod collect_migrations;
mod crate_paths;
mod dto;
mod flatten_imports;
mod hook;
mod http_error_derive;
mod injectable_common;
mod injectable_fn;
mod injectable_struct;
mod installed_apps;
mod macro_state;
mod model_attribute;
mod model_derive;
mod orm_reflectable_derive;
mod pascal_case;
mod path_macro;
mod permission_macro;
mod permissions;
mod pk_shape;
mod query_fields;
mod receiver;
mod rel;
mod routes;
mod routes_registration;
mod schema;
mod settings_compose;
mod settings_fragment;
pub(crate) mod settings_parser;
mod settings_schema;
mod streaming;
mod streaming_patterns;
mod use_inject;
mod user_attribute;
mod user_field_mapping;
mod validate_derive;

use action::action_impl;
use admin::admin_impl;
use api_view::api_view_impl;
use app_config_attribute::app_config_attribute_impl;
use apply_update_attribute::apply_update_attribute_impl;
use apply_update_derive::apply_update_derive_impl;
use http_error_derive::derive_http_error_impl;
use injectable_fn::injectable_fn_impl;
use injectable_struct::injectable_struct_impl;
use installed_apps::installed_apps_impl;
use model_attribute::model_attribute_impl;
use model_derive::model_derive_impl;
use orm_reflectable_derive::orm_reflectable_derive_impl;
use path_macro::path_impl;
use permissions::permission_required_impl;
use query_fields::derive_query_fields_impl;
use receiver::receiver_impl;
use routes::{delete_impl, get_impl, patch_impl, post_impl, put_impl};
use routes_registration::routes_impl;
mod viewset_macro;
mod websocket;
use schema::derive_schema_impl;
use use_inject::use_inject_impl;
use user_attribute::user_attribute_impl;

/// Decorator for function-based API views
#[proc_macro_attribute]
pub fn api_view(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	api_view_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Decorator for ViewSet custom actions
#[proc_macro_attribute]
pub fn action(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	action_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// GET method decorator.
///
/// # Route name (`name = "..."`)
///
/// The optional `name` selects the identifier used for URL reversal
/// (`reverse(...)`). Prefer kebab-case (e.g. `name = "users-list"`) to match
/// ViewSet-generated names; a non-kebab name (snake_case / camelCase) emits a
/// warning at compile time and again when routes are registered. Prefix the
/// name with `!` (e.g. `name = "!legacy_name"`) to opt out — the sigil is
/// stripped before storage, so reverse lookups use the clean name — or set
/// `REINHARDT_URL_NAME_WARNINGS=0` to silence all such warnings. When omitted,
/// the route name defaults to the function name and is exempt from the warning.
/// The same convention applies to `#[post]`, `#[put]`, `#[patch]`, and
/// `#[delete]`. Refs Issue #4901.
#[proc_macro_attribute]
pub fn get(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	get_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// POST method decorator
#[proc_macro_attribute]
pub fn post(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	post_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// PUT method decorator
#[proc_macro_attribute]
pub fn put(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	put_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// PATCH method decorator
#[proc_macro_attribute]
pub fn patch(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	patch_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// DELETE method decorator
#[proc_macro_attribute]
pub fn delete(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	delete_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Producer handler decorator — auto-publishes return value to a Kafka topic.
///
/// # Arguments
///
/// - `topic` — Kafka topic to publish to
/// - `name` — handler identifier for topic resolution via `resolve_streaming_topic()`
///
/// # Example
///
/// ```rust,ignore
/// #[producer(topic = "orders", name = "create_order")]
/// pub async fn create_order(cmd: CreateOrderCommand) -> Result<Order, StreamingError> {
///     Ok(Order::from(cmd))
/// }
/// ```
#[proc_macro_attribute]
pub fn producer(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);
	streaming::producer_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Consumer handler decorator — receives messages from a Kafka topic.
///
/// # Arguments
///
/// - `topic` — Kafka topic to consume from
/// - `group` — Consumer group id
/// - `name` — handler identifier for topic resolution via `resolve_streaming_topic()`
///
/// # Example
///
/// ```rust,ignore
/// #[consumer(topic = "orders", group = "order-processor", name = "handle_order")]
/// pub async fn handle_order(msg: Message<Order>) -> Result<(), StreamingError> {
///     Ok(())
/// }
/// ```
#[proc_macro_attribute]
pub fn consumer(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);
	streaming::consumer_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Streaming patterns attribute — generates per-app streaming topic resolver structs.
///
/// Apply to the function that builds and returns the app's `StreamingRouter`.
/// The function body must contain `streaming_routes![handler1, handler2, ...]`.
///
/// # Arguments
///
/// - First positional arg: `InstalledApp::<Variant>` — the app's label (or any path/ident)
///
/// # Example
///
/// ```rust,ignore
/// #[streaming_patterns(InstalledApp::Orders)]
/// pub fn streaming_routes() -> reinhardt_streaming::StreamingRouter {
///     streaming_routes![create_order, handle_order]
/// }
/// ```
///
/// After this macro expands:
/// - `OrdersStreamingUrls` struct is generated with `.create_order()` and `.handle_order()` methods
/// - Each method returns the Kafka topic name as `&'static str`
#[proc_macro_attribute]
pub fn streaming_patterns(args: TokenStream, input: TokenStream) -> TokenStream {
	streaming_patterns::streaming_patterns_impl(args.into(), input.into())
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Permission required decorator
#[proc_macro_attribute]
pub fn permission_required(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	permission_required_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Defines installed applications with compile-time validation.
///
/// Generates an `InstalledApp` enum with variants for each application,
/// along with `Display`, `FromStr` traits and helper methods.
///
/// **Important**: This macro is for **user applications only**. Built-in framework features
/// (auth, sessions, admin, etc.) are enabled via Cargo feature flags, not through `installed_apps!`.
///
/// # Generated Code
///
/// The macro generates:
///
/// - `enum InstalledApp { ... }` - Type-safe app references with variants for each app
/// - `impl Display` - Convert enum variants to path strings
/// - `impl FromStr` - Parse path strings to enum variants
/// - `fn all_apps() -> Vec<String>` - List all app paths as strings
/// - `fn path(&self) -> &'static str` - Get app path without allocation
///
/// # Example
///
/// ```rust,ignore
/// use reinhardt::installed_apps;
///
/// installed_apps! {
///     users: "users",
///     posts: "posts",
/// }
///
/// // Use generated enum
/// let app = InstalledApp::users;
/// println!("{}", app);  // Output: "users"
///
/// // Get all apps
/// let all = InstalledApp::all_apps();
/// assert_eq!(all, vec!["users".to_string(), "posts".to_string()]);
///
/// // Parse from string
/// use std::str::FromStr;
/// let app = InstalledApp::from_str("users")?;
/// assert_eq!(app, InstalledApp::users);
///
/// // Get path without allocation
/// assert_eq!(app.path(), "users");
/// ```
///
/// # Compile-time Validation
///
/// Framework modules (starting with `reinhardt.`) are validated at compile time.
/// Non-existent modules will cause compilation errors:
///
/// ```rust,ignore
/// installed_apps! {
///     nonexistent: "reinhardt.contrib.nonexistent",
/// }
/// // Compile error: cannot find module `nonexistent` in `contrib`
/// ```
///
/// User apps (not starting with `reinhardt.`) skip compile-time validation,
/// allowing flexible user-defined application names.
///
/// # Framework Features
///
/// **Do NOT use this macro for built-in framework features.** Instead, enable them
/// via Cargo feature flags:
///
/// ```toml
/// [dependencies]
/// reinhardt = { version = "0.1.0-alpha.1", features = ["auth", "sessions", "admin"] }
/// ```
///
/// Then import them directly:
///
/// ```rust,ignore
/// use reinhardt::auth::*;
/// use reinhardt::auth::sessions::*;
/// use reinhardt::admin::*;
/// ```
///
/// # See Also
///
/// - Module documentation in `installed_apps.rs` for detailed information about
///   generated code structure, trait implementations, and advanced usage
/// - `crates/reinhardt-apps/README.md` for comprehensive usage guide
/// - Tutorial: `docs/tutorials/en/basis/1-project-setup.md`
///
#[proc_macro]
pub fn installed_apps(input: TokenStream) -> TokenStream {
	installed_apps_impl(input.into())
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Register URL patterns for automatic discovery by the framework
///
/// This attribute macro automatically registers a function as the URL pattern
/// provider for the framework. The function will be discovered and used when
/// running management commands like `runserver`.
///
/// # Important: Single Usage Only
///
/// **Only one function per project can be annotated with `#[routes]`.**
/// If multiple `#[routes]` attributes are used, the linker will fail with a
/// "duplicate symbol" error for `__reinhardt_routes_registration_marker`.
///
/// To organize routes across multiple files, use the `.mount()` method:
///
/// ```rust,ignore
/// // In src/config/urls.rs - Only ONE #[routes] in the entire project
/// #[routes]
/// pub fn routes() -> UnifiedRouter {
///     UnifiedRouter::new()
///         .mount("/api/", api::routes())   // api::routes() returns UnifiedRouter
///         .mount("/admin/", admin::routes())  // WITHOUT #[routes] attribute
/// }
///
/// // In src/apps/api/urls.rs - NO #[routes] attribute
/// pub fn routes() -> UnifiedRouter {
///     UnifiedRouter::new()
///         .endpoint(views::list)
///         .endpoint(views::create)
/// }
/// ```
///
/// # Supported Function Signatures
///
/// ## 1. Sync function (standard)
///
/// ```rust,ignore
/// #[routes]
/// pub fn routes() -> UnifiedRouter {
///     UnifiedRouter::new()
///         .endpoint(views::index)
///         .mount("/api/", api::routes())
/// }
/// ```
///
/// ## 2. Async function (no DI)
///
/// ```rust,ignore
/// #[routes]
/// pub async fn routes() -> UnifiedRouter {
///     UnifiedRouter::new()
///         .mount("/api/", api::routes())
/// }
/// ```
///
/// ## 3. Async function with `#[inject]` (DI-aware)
///
/// ```rust,ignore
/// #[routes]
/// pub async fn routes(#[inject] router: UnifiedRouter) -> UnifiedRouter {
///     router
/// }
/// ```
///
/// When `#[inject]` parameters are present, the macro automatically creates
/// a DI context (`SingletonScope` + `InjectionContext`) and resolves each
/// injected dependency before calling the function.
///
/// # Arguments
///
/// The `#[routes]` macro does not accept any arguments. It only emits
/// `inventory::submit!(UrlPatternsRegistration)` and a linker marker.
///
/// Previous flags (`standalone`, `client_inventory`, `server_only`,
/// `no_client_resolvers`, `no_ws_resolvers`) were removed as part of
/// the URL routing simplification (Issue #4784).
///
/// # Notes
///
/// - The function can have any name (e.g., `routes`, `app_routes`, `url_patterns`)
/// - The return type must be `UnifiedRouter` (not `Arc<UnifiedRouter>`)
/// - The framework automatically wraps the router in `Arc`
/// - Sync functions cannot use `#[inject]` (DI resolution is inherently async)
#[proc_macro_attribute]
pub fn routes(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	routes_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Generate URL resolver traits for a ViewSet function.
///
/// When applied to a function returning a ViewSet (e.g., `ModelViewSet`), extracts
/// the basename from the function body and generates `__url_resolver_{basename}_list`
/// and `__url_resolver_{basename}_detail` modules.
///
/// # Example
///
/// ```rust,ignore
/// #[viewset]
/// pub fn viewset() -> ModelViewSet<Snippet, SnippetSerializer> {
///     ModelViewSet::new("snippet")
/// }
/// // Generates: __url_resolver_snippet_list, __url_resolver_snippet_detail
/// ```
///
#[doc = include_str!("upstream_workaround_note.md")]
#[proc_macro_attribute]
pub fn viewset(args: TokenStream, input: TokenStream) -> TokenStream {
	viewset_macro::viewset_macro_impl(args.into(), input.into())
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Validate URL patterns at compile time
///
/// This macro validates URL pattern syntax at compile time, catching common errors
/// before they reach runtime. It supports both simple parameters and Django-style
/// typed parameters.
///
/// # Compile-time Validation
///
/// The macro will fail to compile if:
/// - Braces are not properly matched (e.g., `{id` or `id}`)
/// - Parameter names are empty (e.g., `{}`)
/// - Parameter names contain invalid characters
/// - Type specifiers are invalid (valid: `int`, `str`, `uuid`, `slug`, `path`)
/// - Django-style parameters are used outside braces (e.g., `<int:id>` instead of `{<int:id>}`)
///
/// # Supported Type Specifiers
///
/// - `int` - Integer values
/// - `str` - String values
/// - `uuid` - UUID values
/// - `slug` - Slug strings (alphanumeric, hyphens, underscores)
/// - `path` - Path segments (can include slashes)
///
#[proc_macro]
pub fn path(input: TokenStream) -> TokenStream {
	path_impl(input.into())
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Connect a receiver function to a signal automatically
///
/// This macro provides Django-style `@receiver` decorator functionality for Rust.
/// It automatically registers the function as a signal receiver at startup.
///
#[proc_macro_attribute]
pub fn receiver(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	receiver_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Attribute macro for registering lifecycle hooks.
///
/// Currently supports `runserver` hooks for extending server startup behavior.
///
/// # Usage
///
/// ```rust,ignore
/// use reinhardt::commands::{RunserverHook, RunserverContext};
///
/// #[reinhardt::hook(on = runserver)]
/// struct MyValidationHook;
///
/// #[async_trait]
/// impl RunserverHook for MyValidationHook {
///     async fn validate(&self) -> Result<(), Box<dyn Error + Send + Sync>> {
///         // Fail-fast validation before server starts
///         Ok(())
///     }
/// }
/// ```
#[proc_macro_attribute]
pub fn hook(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemStruct);
	hook::hook_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Automatic dependency injection macro
///
/// This macro enables FastAPI-style dependency injection using parameter attributes.
/// Parameters marked with `#[inject]` will be automatically resolved from the
/// `InjectionContext`. Can be used with any function, not just endpoints.
///
/// # Generated Code
///
/// The macro transforms the function by:
/// 1. Removing `#[inject]` parameters from the signature
/// 2. Adding an `InjectionContext` parameter
/// 3. Injecting dependencies at the start of the function
///
#[proc_macro_attribute]
pub fn use_inject(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);

	use_inject_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for type-safe field lookups
///
/// Automatically generates field accessor methods for models, enabling
/// compile-time validated field lookups.
///
/// # Generated Methods
///
/// For each field in the struct, the macro generates a static method that
/// returns a `Field<Model, FieldType>`. The field type determines which
/// lookup methods are available:
///
/// - String fields: `lower()`, `upper()`, `trim()`, `contains()`, etc.
/// - Numeric fields: `abs()`, `ceil()`, `floor()`, `round()`
/// - DateTime fields: `year()`, `month()`, `day()`, `hour()`, etc.
/// - All fields: `eq()`, `ne()`, `gt()`, `gte()`, `lt()`, `lte()`
///
#[proc_macro_derive(QueryFields)]
pub fn derive_query_fields(input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	derive_query_fields_impl(input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for automatic OpenAPI schema generation
///
/// Automatically implements the `ToSchema` trait for structs and enums,
/// generating OpenAPI 3.0 schemas from Rust type definitions.
///
/// # Supported Types
///
/// - Primitives: `String`, `i32`, `i64`, `f32`, `f64`, `bool`
/// - `Option<T>`: Makes fields optional in the schema
/// - `Vec<T>`: Generates array schemas
/// - Custom types implementing `ToSchema`
///
/// # Features
///
/// - Automatic field metadata extraction
/// - Documentation comments become field descriptions
/// - Required/optional field detection
/// - Nested schema support
/// - Enum variant handling
///
#[proc_macro_derive(Schema)]
pub fn derive_schema(input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	derive_schema_impl(input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Implements HTTP status and client-message mapping for application error enums.
#[proc_macro_derive(HttpError, attributes(http_error))]
pub fn derive_http_error(input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	derive_http_error_impl(input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Attribute macro for injectable factory/provider functions and structs
///
/// This macro can be applied to both functions and structs to enable dependency injection.
///
/// # Field Attributes (Struct Only)
///
/// All struct fields must have either `#[inject]` or `#[no_inject]` attribute:
///
/// - **`#[inject]`**: Inject this field from the DI container
/// - **`#[inject(cache = false)]`**: Inject without caching
/// - **`#[inject(scope = Singleton)]`**: Use singleton scope
/// - **`#[no_inject(default = Default)]`**: Initialize with `Default::default()`
/// - **`#[no_inject(default = value)]`**: Initialize with specific value
/// - **`#[no_inject]`**: Initialize with `None` (field must be `Option<T>`)
///
/// # Restrictions
///
/// **For functions:**
/// - Function must have an explicit return type
/// - All parameters must be marked with `#[inject]`
///
/// **For structs:**
/// - Struct must have named fields
/// - All fields must have either `#[inject]` or `#[no_inject]` attribute
/// - `#[no_inject]` without default value requires field type to be `Option<T>`
/// - `Clone` is auto-derived if not already present (used by generated injection and caching paths)
/// - All `#[inject]` field types must implement `Injectable` or `InjectableType`
///
/// # Attribute Ordering
///
/// **`#[injectable]` must be placed above `#[derive(...)]` attributes.**
///
/// In Rust 2024 edition, attribute macros can only see attributes listed
/// below them. If `#[derive(Clone)]` appears above `#[injectable]`, the
/// macro cannot detect it and will add a duplicate `#[derive(Clone)]`,
/// causing a compilation error.
///
/// ```ignore
/// // Correct
/// #[injectable]
/// #[derive(Default, Debug)]
/// struct MyService { /* ... */ }
///
/// // Incorrect — may cause duplicate Clone derive
/// #[derive(Default, Debug)]
/// #[injectable]
/// struct MyService { /* ... */ }
/// ```
///
#[proc_macro_attribute]
pub fn injectable(args: TokenStream, input: TokenStream) -> TokenStream {
	// Try to parse as ItemFn first
	if let Ok(item_fn) = syn::parse::<ItemFn>(input.clone()) {
		return injectable_fn_impl(proc_macro2::TokenStream::new(), item_fn)
			.unwrap_or_else(|e| e.to_compile_error())
			.into();
	}

	// Try to parse as ItemStruct
	if let Ok(item_struct) = syn::parse::<ItemStruct>(input.clone()) {
		// Convert ItemStruct to DeriveInput for compatibility
		let derive_input = syn::DeriveInput {
			attrs: item_struct.attrs,
			vis: item_struct.vis,
			ident: item_struct.ident,
			generics: item_struct.generics,
			data: syn::Data::Struct(syn::DataStruct {
				struct_token: item_struct.struct_token,
				fields: item_struct.fields,
				semi_token: item_struct.semi_token,
			}),
		};

		return injectable_struct_impl(args.into(), derive_input)
			.unwrap_or_else(|e| e.to_compile_error())
			.into();
	}

	// Neither ItemFn nor ItemStruct
	syn::Error::new(
		proc_macro2::Span::call_site(),
		"#[injectable] can only be applied to functions or structs",
	)
	.to_compile_error()
	.into()
}

/// Attribute macro for Django-style model definition with automatic derive
///
/// Automatically adds `#[derive(Model)]` and keeps the `#[model(...)]` attribute.
/// This provides a cleaner syntax by eliminating the need to explicitly write
/// `#[derive(Model)]` on every model struct.
///
/// # Info Companion Type (Issues #4194, #5272)
///
/// By default, generates a `{Model}Info` companion struct with `pub` fields,
/// bidirectional `From` conversions, and a typestate builder. Relationship
/// fields use lightweight `RelationInfo<T>` and `ManyToManyInfo<Source, Target>`
/// payloads instead of ORM marker fields or flattened `*_id` fields. FK and
/// OneToOne builder setters accept `impl IntoPrimaryKey<T>`. Validation
/// attributes are derived from `#[field(...)]` config. Opt out with
/// `#[model(info = false)]`. Exclude individual fields with
/// `#[field(skip_info = true)]`.
///
/// # Model Attributes
///
/// Same as `#[derive(Model)]`. See [`derive_model`] for details.
///
#[proc_macro_attribute]
pub fn model(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemStruct);

	model_attribute_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Attribute macro for generating auth trait implementations.
///
/// Generates `BaseUser`, `FullUser` (when `full = true`), `PermissionsMixin`
/// (when `user_permissions` and `groups` fields exist), and `AuthIdentity`
/// trait implementations based on struct fields.
///
/// # Arguments
///
/// - `hasher`: Type implementing `PasswordHasher + Default` (required)
/// - `username_field`: Name of the field used as username (required)
/// - `full`: Generate `FullUser` impl (default: `false`)
///
/// # Password Hash Info Exclusion
///
/// When `#[user]` is combined with `#[model]`, the mapped password-hash field
/// is automatically excluded from the generated `{User}Info` companion on both
/// native and WASM targets. Converting `{User}Info` back into the model uses the
/// password-hash field's default value. No explicit
/// `#[field(skip_info = true)]` annotation is required for that mapped field.
///
/// # Examples
///
/// ```rust,ignore
/// #[user(hasher = reinhardt::Argon2Hasher, username_field = "email", full = true)]
/// #[derive(Serialize, Deserialize)]
/// pub struct MyUser {
///     pub id: Uuid,
///     pub email: String,
///     pub password_hash: Option<String>,
///     pub last_login: Option<DateTime<Utc>>,
///     pub is_active: bool,
///     pub is_superuser: bool,
/// }
/// ```
#[proc_macro_attribute]
pub fn user(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemStruct);

	user_attribute_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for automatic Model implementation and migration registration
///
/// Automatically implements the `Model` trait and registers the model with the global
/// ModelRegistry for automatic migration generation.
///
/// # Model Attributes
///
/// - `app_label`: Application label (default: "default")
/// - `table_name`: Database table name (default: struct name in snake_case)
/// - `constraints`: List of unique constraints (e.g., `unique(fields = ["field1", "field2"], name = "name")`)
///
/// # Field Attributes
///
/// - `primary_key`: Mark field as primary key (required for exactly one field)
/// - `max_length`: Maximum length for String fields (required for String)
/// - `null`: Allow NULL values (default: inferred from `Option<T>`)
/// - `blank`: Allow blank values in forms
/// - `unique`: Enforce uniqueness constraint
/// - `default`: Default value
/// - `db_column`: Custom database column name
/// - `editable`: Whether field is editable (default: true)
///
/// # Supported Types
///
/// - `i32` → IntegerField
/// - `i64` → BigIntegerField
/// - `String` → CharField (requires max_length)
/// - `bool` → BooleanField
/// - `DateTime<Utc>` → DateTimeField
/// - `Date` → DateField
/// - `Time` → TimeField
/// - `f32`, `f64` → FloatField
/// - `Option<T>` → Sets null=true automatically
///
/// # Requirements
///
/// - Struct must have named fields
/// - Struct must implement `Serialize` and `Deserialize`
/// - Exactly one field must be marked with `primary_key = true`
/// - String fields must specify `max_length`
///
#[proc_macro_derive(
	Model,
	attributes(
		model,
		model_config,
		field,
		rel,
		fk_id_field,
		reinhardt_internal_relation_serde_skip
	)
)]
pub fn derive_model(input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	model_derive_impl(input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for automatic OrmReflectable implementation
///
/// Automatically implements the `OrmReflectable` trait for structs,
/// enabling reflection-based field and relationship access for association proxies.
///
/// ## Type Inference
///
/// Fields are automatically classified based on their types:
/// - `Vec<T>` → Collection relationship
/// - `Option<T>` (where T is non-primitive) → Scalar relationship
/// - Primitive types (i32, String, etc.) → Regular fields
///
/// ## Attributes
///
/// Override automatic inference with explicit attributes:
///
/// - `#[orm_field(type = "Integer")]` - Mark as regular field with specific type
/// - `#[orm_relationship(type = "collection")]` - Mark as collection relationship
/// - `#[orm_relationship(type = "scalar")]` - Mark as scalar relationship
/// - `#[orm_ignore]` - Exclude field from reflection
///
/// ## Supported Field Types
///
/// - **Integer**: i8, i16, i32, i64, i128, u8, u16, u32, u64, u128
/// - **Float**: f32, f64
/// - **Boolean**: bool
/// - **String**: String, str
///
#[proc_macro_derive(OrmReflectable, attributes(orm_field, orm_relationship, orm_ignore))]
pub fn derive_orm_reflectable(input: TokenStream) -> TokenStream {
	orm_reflectable_derive_impl(input)
}

/// Attribute macro for Django-style AppConfig definition with automatic derive
///
/// Automatically adds `#[derive(AppConfig)]` and keeps the `#[app_config(...)]` attribute.
/// This provides a cleaner syntax by eliminating the need to explicitly write
/// `#[derive(AppConfig)]` on every app config struct.
///
/// # Example
///
/// ```rust,ignore
/// #[app_config(name = "hello", label = "hello")]
/// pub struct HelloConfig;
///
/// // Generates a config() method:
/// let config = HelloConfig::config();
/// assert_eq!(config.name, "hello");
/// assert_eq!(config.label, "hello");
/// ```
///
/// # Attributes
///
/// - `name`: Application name (required, string literal)
/// - `label`: Application label (required, string literal)
/// - `verbose_name`: Verbose name (optional, string literal)
///
/// # Note
///
/// Direct use of `#[derive(AppConfig)]` is not allowed. Always use
/// `#[app_config(...)]` attribute macro instead.
///
#[proc_macro_attribute]
pub fn app_config(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemStruct);

	app_config_attribute_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for automatic AppConfig factory method generation
///
/// **Note**: Do not use this derive macro directly. Use `#[app_config(...)]`
/// attribute macro instead.
///
/// This derive macro is invoked automatically by the `#[app_config(...)]` attribute.
/// Direct use will result in a compile error.
///
#[proc_macro_derive(AppConfig, attributes(app_config, app_config_internal))]
pub fn derive_app_config(input: TokenStream) -> TokenStream {
	app_config_derive::derive(input)
}

/// Collect migrations and register them with the global registry
///
/// # Deprecated since 0.2.0
///
/// **This macro is deprecated.** Use `FilesystemSource` instead for loading migrations.
/// `FilesystemSource` scans directories for `.rs` migration files and does not require
/// compile-time registration. It is consistent with `manage migrate` behavior and
/// works reliably in Cargo workspaces when using `env!("CARGO_MANIFEST_DIR")`.
///
/// This macro generates a `MigrationProvider` implementation and automatically
/// registers it with the global migration registry using `linkme::distributed_slice`.
///
/// # Requirements
///
/// - Each migration module must export a `migration()` function returning `Migration`
/// - The crate must have `reinhardt-migrations` and `linkme` as dependencies
///
#[proc_macro]
pub fn collect_migrations(input: TokenStream) -> TokenStream {
	collect_migrations::collect_migrations_impl(input.into())
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Attribute macro for ModelAdmin configuration
///
/// Automatically implements the `ModelAdmin` trait for a struct with compile-time
/// field validation against the specified model type.
///
/// # Attributes
///
/// ## Required
///
/// - `for = ModelType` - The model type to validate fields against
/// - `name = "ModelName"` - The display name for the model
///
/// ## Optional
///
/// - `list_display = [field1, field2, ...]` - Fields to display in list view (default: `[id]`)
/// - `list_filter = [field1, field2, ...]` - Fields for filtering (default: `[]`)
/// - `search_fields = [field1, field2, ...]` - Fields for search (default: `[]`)
/// - `fields = [field1, field2, ...]` - Fields to display in forms (default: all)
/// - `readonly_fields = [field1, field2, ...]` - Read-only fields (default: `[]`)
/// - `ordering = [(field1, asc/desc), ...]` - Default ordering (default: `[(id, desc)]`)
/// - `list_per_page = N` - Items per page (default: site default)
///
/// # Compile-time Field Validation
///
/// All field names are validated at compile time against the model's `field_xxx()` methods.
/// If a field doesn't exist, compilation will fail with an error.
///
/// # Generated Code
///
/// The macro generates:
/// 1. The struct definition
/// 2. Compile-time field validation code
/// 3. `ModelAdmin` trait implementation with `#[async_trait]`
///
#[proc_macro_attribute]
pub fn admin(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemStruct);

	admin_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Attribute macro for applying partial updates to target structs
///
/// Automatically adds `#[derive(ApplyUpdate)]` and creates a helper config attribute.
/// This provides a cleaner syntax for defining update request structs.
///
/// # Attributes
///
/// - `target(Type1, Type2, ...)`: Target types to generate `ApplyUpdate` implementations for
///
/// # Field Attributes
///
/// - `#[apply_update(skip)]`: Skip this field during update application
/// - `#[apply_update(rename = "field_name")]`: Use a different field name on the target
///
#[proc_macro_attribute]
pub fn apply_update(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemStruct);

	apply_update_attribute_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for automatic `ApplyUpdate` trait implementation
///
/// **Note**: Do not use this derive macro directly. Use `#[apply_update(...)]`
/// attribute macro instead.
///
#[proc_macro_derive(ApplyUpdate, attributes(apply_update, apply_update_config))]
pub fn derive_apply_update(input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	apply_update_derive_impl(input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Derive macro for struct-level validation
///
/// Implements the `Validate` trait using `#[validate(...)]` field attributes
/// to call Reinhardt's built-in validators.
///
/// # Supported Attributes
///
/// - `#[validate(email)]` - Validate email format
/// - `#[validate(url)]` - Validate URL format
/// - `#[validate(length(min = N, max = M))]` - Validate string length
/// - `#[validate(range(min = N, max = M))]` - Validate numeric range
/// - `message = "..."` - Custom error message (inside rule parentheses)
///
/// `Option<T>` fields are skipped when `None`.
///
#[proc_macro_derive(Validate, attributes(validate))]
pub fn derive_validate(input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	validate_derive::validate_derive_impl(input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Attribute macro that absorbs the `cfg_attr(native, ...)` boilerplate for
/// DTOs shared between the server (`native` cfg) and client (`wasm`) builds.
///
/// The macro:
///
/// 1. Emits `#[cfg_attr(native, derive(::reinhardt::Validate))]`
///    on the struct so the server build gets validation while the wasm build
///    sees a plain serializable type. With the explicit `schema` option, it
///    also emits `::reinhardt::rest::openapi::Schema` on native builds.
/// 2. Wraps every `#[validate(...)]` and `#[schema(...)]` attribute in
///    `#[cfg_attr(native, ...)]` so the same source compiles unchanged for
///    `wasm32-unknown-unknown`.
/// 3. Is idempotent: if the user already wrote
///    `#[cfg_attr(native, derive(Validate))]` on the struct, that derive is
///    not duplicated.
///
/// # `#[dto]` vs [`macro@model`]
///
/// Both are struct attributes, but they describe different things and live in
/// different files:
///
/// | | `#[model]` (ORM) | `#[dto]` (this macro) |
/// |---|---|---|
/// | What | A persistent record | A wire-level data shape |
/// | Where it lives | `apps/<app>/models/*.rs` | `apps/<app>/shared/types.rs` |
/// | Where it runs | Server only (`native`) | Both server (`native`) and client (`wasm`) |
/// | What it adds | Table mapping, primary key, FK fields, migrations | `Validate` derive (native-only), optional `Schema` derive, wraps `#[validate(...)]` |
/// | Boundary it crosses | Rust ↔ database | Server ↔ client (via `#[server_fn]`, REST handlers, WebSocket payloads) |
///
/// "DTO" is the industry-standard term for the second row — a data-transfer
/// object that is serialized on one side, sent over the wire, and
/// deserialized on the other side.
///
/// # Example
///
/// ```rust,ignore
/// use reinhardt::dto;
/// use serde::{Deserialize, Serialize};
///
/// #[dto(schema)]
/// #[derive(Debug, Clone, Serialize, Deserialize)]
/// pub struct LoginRequest {
///     #[validate(email(message = "Invalid email address"))]
///     pub email: String,
///
///     #[validate(length(min = 1, message = "Password is required"))]
///     pub password: String,
/// }
/// ```
///
/// Expands (conceptually) to:
///
/// ```rust,ignore
/// #[cfg_attr(native, derive(::reinhardt::Validate, ::reinhardt::rest::openapi::Schema))]
/// #[derive(Debug, Clone, Serialize, Deserialize)]
/// pub struct LoginRequest {
///     #[cfg_attr(native, validate(email(message = "Invalid email address")))]
///     pub email: String,
///
///     #[cfg_attr(native, validate(length(min = 1, message = "Password is required")))]
///     pub password: String,
/// }
/// ```
///
/// # Requirements
///
/// - OpenAPI schema generation is not implicit. Add `schema` as an explicit
///   option (`#[dto(schema)]`) for a DTO that should be part of generated
///   OpenAPI documentation. The consumer's native build must enable the
///   `openapi` feature.
/// - Applies only to `struct` items (named, tuple, or unit). Enums and unions
///   produce a compile error. The `schema` option additionally requires named
///   fields because the OpenAPI `Schema` derive does not support tuple or unit
///   structs.
/// - The only supported argument is the bare `schema` option. Other arguments
///   produce a compile error.
/// - Unconditional `#[derive(Validate)]` is a compile error. `Validate` lives
///   behind the `native` cfg, so an unconditional derive cannot resolve on wasm
///   and would duplicate the macro's emission on native. Either delete the
///   derive (and let `#[dto]` emit it) or wrap it in
///   `#[cfg_attr(native, derive(Validate))]` yourself. When using
///   `#[dto(schema)]`, do not add a separate `Schema` derive because the
///   option emits it for native builds.
/// - Existing `Validate` derives may use a qualified path; the final path
///   segment is used when checking for an existing derive.
/// - Existing `Schema` derives may use the facade path or a directly referenced
///   `reinhardt_rest::openapi::Schema` path.
/// - Any pre-existing `#[cfg_attr(native, derive(Validate))]` MUST be written
///   *below* `#[dto]`,
///   not above it. Attribute proc macros only observe attributes that appear
///   under them in source order, so a `cfg_attr` placed above `#[dto]` is
///   invisible to the macro and would cause `#[dto]` to emit a duplicate
///   `cfg_attr(native, derive(...))` on native. Example of the supported
///   ordering:
///
/// ```rust,ignore
/// #[dto(schema)]
/// #[cfg_attr(native, derive(Validate))]
/// pub struct LoginRequest { /* ... */ }
/// ```
#[proc_macro_attribute]
pub fn dto(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as syn::DeriveInput);

	dto::dto_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Settings attribute macro for composable configuration.
///
/// # Fragment mode
///
/// Marks a struct as a root settings fragment:
///
/// ```rust,ignore
/// #[settings(fragment = true, section = "cache")]
/// pub struct CacheSettings {
///     pub backend: String,
/// }
/// ```
///
/// Omitting `section = "..."` creates an embedded settings node instead of a
/// root fragment. Embedded nodes participate in recursive schema metadata and
/// required-field validation below a root fragment, but they do not implement
/// `SettingsFragment` and cannot be composed directly:
///
/// ```rust,ignore
/// #[settings(fragment = true, default_policy = "required")]
/// pub struct DatabaseConfig {
///     pub engine: String,
///     pub host: String,
/// }
/// ```
///
/// Fields whose released Rust type cannot use a secret wrapper can opt into
/// secret schema classification explicitly. The generated schema then exposes
/// a leaf in settings metadata and includes the field in redaction paths while
/// preserving its ordinary typed `FieldRef`:
///
/// ```rust,ignore
/// #[settings(fragment = true, section = "service")]
/// pub struct ServiceSettings {
///     #[setting(secret)]
///     pub api_key: String,
/// }
/// ```
///
/// # Composition mode
///
/// Composes fragments into a project settings struct.
///
/// Supports two syntax forms:
/// - **Explicit**: `key: Type` — specify field name explicitly
/// - **Implicit**: `Type` — infer field name from type (requires `Settings` suffix)
///
/// Both forms can be mixed freely:
///
/// ```rust,ignore
/// // All implicit (XxxSettings → xxx)
/// #[settings(CoreSettings | CacheSettings | SessionSettings)]
/// pub struct ProjectSettings;
///
/// // Mixed implicit + explicit
/// #[settings(CoreSettings | CacheSettings | static_files: StaticSettings)]
/// pub struct ProjectSettings;
///
/// // Explicit only (original syntax, still fully supported)
/// #[settings(core: CoreSettings | cache: CacheSettings)]
/// pub struct ProjectSettings;
/// ```
///
/// Types without `Settings` suffix require explicit `key: Type` syntax. Note that
/// even for `*Settings` types, if the inferred field name would be a Rust keyword
/// (e.g. `StaticSettings` → `static`), you must use explicit `key: Type` syntax,
/// as in `static_files: StaticSettings` above.
#[proc_macro_attribute]
pub fn settings(args: TokenStream, input: TokenStream) -> TokenStream {
	let input_struct = parse_macro_input!(input as ItemStruct);

	// Detect mode: if args contain "fragment", use fragment handler
	let args_str = args.to_string();
	if args_str.contains("fragment") {
		settings_fragment::settings_fragment_impl(args.into(), input_struct)
			.unwrap_or_else(|e| e.to_compile_error())
			.into()
	} else {
		settings_compose::settings_compose_impl(args.into(), input_struct)
			.unwrap_or_else(|e| e.to_compile_error())
			.into()
	}
}

/// WebSocket consumer macro. Parallel to `#[get]` / `#[post]`.
///
/// Annotates an `async fn` that handles WebSocket messages (`on_message`).
/// Generates a `{FnName}Consumer` struct implementing `WebSocketConsumer`,
/// a factory function, inventory metadata, and URL resolver extension traits.
///
/// # Example
///
/// ```ignore
/// use reinhardt::websocket;
/// use reinhardt_websockets::consumers::{ConsumerContext, WebSocketResult};
/// use reinhardt_websockets::connection::Message;
///
/// #[websocket("/ws/chat/{room_id}/", name = "chat_ws")]
/// pub async fn chat_ws(
///     context: &mut ConsumerContext,
///     message: Message,
/// ) -> WebSocketResult<()> {
///     context.send_text("pong".to_string()).await
/// }
/// ```
#[proc_macro_attribute]
pub fn websocket(args: TokenStream, input: TokenStream) -> TokenStream {
	let input = parse_macro_input!(input as ItemFn);
	websocket::websocket_impl(args.into(), input)
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}

/// Function-like proc macro for multi-file view modules.
///
/// When a view module uses per-file endpoint organization (one file per view in
/// `views/`), the URL resolver modules generated by `#[get]`/`#[post]`/etc.
/// live inside the submodules. This macro generates `pub use submod::*;`
/// for each `pub mod` declaration, bringing endpoint functions and their
/// resolver modules into the parent module scope.
///
/// This enables resolvers to be discovered using the standard
/// parent-module path convention (e.g., `.endpoint(views::login)`).
///
/// # Usage
///
/// ```rust,ignore
/// // views.rs (multi-file pattern)
/// use reinhardt::flatten_imports;
///
/// flatten_imports! {
///     pub mod login;
///     pub mod register;
/// }
///
/// // Generates:
/// //   pub mod login;
/// //   pub mod register;
/// //   pub use login::*;
/// //   pub use register::*;
/// ```
///
/// For single-file views where all functions are defined directly in
/// `views.rs`, this macro is not needed.
#[proc_macro]
pub fn flatten_imports(input: TokenStream) -> TokenStream {
	flatten_imports::flatten_imports_impl(input.into())
		.unwrap_or_else(|e| e.to_compile_error())
		.into()
}