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
//!

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

mod action;
mod admin;
mod api_view;
// client_routes module removed: superseded by #[url_patterns(InstalledApp::<variant>, mode = client)]
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 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 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 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 url_patterns;
mod viewset_macro;
mod websocket;
use schema::derive_schema_impl;
use url_patterns::url_patterns_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
#[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` — identifier used in `ResolvedUrls::streaming().<app>().<name>()`
///
/// # 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` — identifier used in `ResolvedUrls::streaming().<app>().<name>()`
///
/// # 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 typed per-app streaming URL accessors.
///
/// 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
/// - `urls.streaming().orders()` returns `OrdersStreamingUrls<'_>` (requires `#[routes]` in same crate)
/// - 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
///
/// - `#[routes]` — Default mode. Generates `ResolvedUrls` and `url_prelude`
///   module with URL resolver traits from all installed apps. Requires
///   `installed_apps!` to be present in the crate.
/// - `#[routes(standalone)]` — Standalone mode. Generates `ResolvedUrls` only,
///   without `url_prelude` module. Use this for projects that don't use
///   `installed_apps!`.
/// - `#[routes(client_inventory)]` — Opt into the WASM cross-target
///   `ClientRouter` `inventory::submit!` registration (see Issue #4453).
///
/// ## Per-mode resolver suppression (Issue #4509)
///
/// Plain `#[routes]` unconditionally emits per-app resolver lookups for
/// three modes (server, client, ws). REST-only apps that do not use
/// `#[url_patterns(InstalledApp::<app>, mode = client)]` or
/// `#[url_patterns(InstalledApp::<app>, mode = ws)]` would need to stub
/// the missing modules. These flags let the macro skip the unused lookups:
///
/// - `#[routes(server_only)]` — Shorthand for
///   `no_client_resolvers, no_ws_resolvers`. The `urls.client()` /
///   `urls.ws()` gateways are not emitted; only `urls.server().<app>()`
///   remains. The `ResolvedUrls::<app>()` server-side accessor is
///   preserved (unlike `standalone`, which suppresses it).
/// - `#[routes(no_client_resolvers)]` — Skip per-app client resolver
///   lookups and the `ClientUrls` / `<app>ClientUrls` types.
/// - `#[routes(no_ws_resolvers)]` — Skip per-app WebSocket resolver
///   lookups, the `WsUrls` / `<app>WsUrls` types, and the stub
///   `WebSocketUrlResolver` impl on `ResolvedUrls`.
///
/// `client_inventory` is mutually exclusive with the `no_*` flags
/// (and therefore with `server_only`) — `client_inventory` registers
/// the very WASM client surface those flags suppress.
///
/// ```rust,ignore
/// // REST-only project with #[url_patterns(InstalledApp::api, mode = server)]
/// // — no stub client_router.rs / ws_urls.rs needed. `server_only` only
/// // gates per-app client/ws emission, so the return type stays
/// // `UnifiedRouter` for consistency with every other `#[routes]` example.
/// #[routes(server_only)]
/// pub fn routes() -> UnifiedRouter {
///     UnifiedRouter::new().mount("/api/", api::urls::url_patterns())
/// }
///
/// // HTTP + WebSocket but no WASM admin: skip client resolvers only.
/// #[routes(no_client_resolvers)]
/// pub fn routes() -> UnifiedRouter { ... }
/// ```
///
/// # 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()
}

/// Register an app-scoped URL pattern function with the framework and
/// generate per-mode helper modules from its body.
///
/// # Syntax
///
/// ```text
/// #[url_patterns(<InstalledApp::variant>, mode = server|client|unified|ws)]
/// pub fn url_patterns() -> Router { ... }
/// ```
///
/// The first argument is a path to a variant of an enum implementing
/// `reinhardt_apps::apps::AppLabel` — normally the `InstalledApp`
/// enum generated by `installed_apps!`. The macro wraps the original
/// function so the returned router carries the variant's
/// `AppLabel::path(&variant)` value as its runtime namespace.
///
/// # Modes
///
/// | mode      | Router          | Scanned calls                                                            | Modules emitted                                    |
/// |-----------|-----------------|--------------------------------------------------------------------------|----------------------------------------------------|
/// | `server`  | `ServerRouter`  | `.endpoint()`, `.viewset()`, `.mount()`                                  | `url_resolvers`                                    |
/// | `client`  | `ClientRouter`  | `.named_route()` / `.named_route_path*()` family                         | `client_url_resolvers` + `urls` (typed helpers)    |
/// | `unified` | `UnifiedRouter` | both sides (inside `.server(\|s\| ...)` / `.client(\|c\| ...)` closures) | `url_resolvers` + `client_url_resolvers` + `urls`  |
/// | `ws`      | `WsRouter`      | `.consumer(...)`                                                         | `ws_url_resolvers`                                 |
///
/// # The `urls` module (Issue #4644)
///
/// For `mode = client` and the client side of `mode = unified`, the macro
/// emits a sibling `pub mod urls` whose contents mirror the named routes
/// declared in the function body. Each named route appears as a free
/// function whose signature carries the path parameters lifted from the
/// closure binding:
///
/// ```text
/// // Input
/// #[url_patterns(InstalledApp::polls, mode = client)]
/// pub fn client_url_patterns() -> ClientRouter {
///     ClientRouter::new()
///         .named_route("index", "/", index_page)
///         .named_route_path(
///             "detail",
///             "/polls/{question_id}/",
///             |ClientPath(question_id): ClientPath<i64>| polls_detail_page(question_id),
///         )
/// }
///
/// // Generated (sketch)
/// pub mod urls {
///     pub fn index() -> String { /* "polls:index" via global reverser */ }
///     pub fn detail(question_id: i64) -> String { /* "polls:detail" */ }
/// }
/// ```
///
/// Each helper resolves through the global `ClientUrlReverser`
/// (`reinhardt::get_client_reverser()`), so a route-pattern change in the
/// `#[url_patterns]` body propagates without any call-site edits.
///
/// **Extraction rules.** A typed helper is generated when the path
/// parameter count in the pattern matches the binding count in the
/// closure, and every binding is shaped `ClientPath(name): ClientPath<T>`:
///
/// - `.named_route(name, pattern, component)` — always emits a zero-arg
///   helper.
/// - `.named_route_path(name, pattern, |ClientPath(id): ClientPath<T>| ...)`
///   — emits `fn name(id: T) -> String`.
/// - `.named_route_path2(...)` / `.named_route_path3(...)` — emit helpers
///   with two / three positional parameters, in binding order.
/// - `.named_route_params(...)` / `.named_route_result(...)` — the macro
///   does not project these into typed helpers today; the route is still
///   reachable through the stringly-typed
///   `ResolvedUrls::resolve_client_url(...)` API.
/// - Routes whose handler is a function reference (not an inline closure)
///   are silently skipped in the `urls` module for the same reason.
///
/// The `urls` module is emitted unconditionally so call sites can write
/// `use ...::urls;` regardless of which routes happen to be typed; an
/// empty module is harmless.
#[doc = include_str!("upstream_workaround_note.md")]
#[proc_macro_attribute]
pub fn url_patterns(args: TokenStream, input: TokenStream) -> TokenStream {
	url_patterns_impl(args.into(), input.into())
		.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()
}

/// 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 `into_inner()` and `injectable_factory` patterns)
/// - All `#[inject]` field types must implement `Injectable`
///
/// # 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.
///
/// # 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`)
///
/// # Examples
///
/// ```rust,ignore
/// #[user(hasher = 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))]
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, ::reinhardt::rest::openapi::Schema))]`
///    on the struct so the server build gets validation and OpenAPI schema
///    generation, while the wasm build sees a plain serializable type.
/// 2. Wraps every `#[validate(...)]` field 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))]` or
///    `#[cfg_attr(native, derive(Schema))]` 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 + OpenAPI `Schema` derives (native-only), 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]
/// #[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
///
/// - The consumer crate's **native** build of `reinhardt` MUST enable the
///   `rest` feature — the macro expansion references
///   `::reinhardt::rest::openapi::Schema`.
/// - Applies only to `struct` items (named, tuple, or unit). Enums and unions
///   produce a compile error.
/// - Does not accept arguments in this version. Passing any tokens (e.g.
///   `#[dto(no_schema)]`) is a compile error.
/// - Unconditional `#[derive(Validate)]` or `#[derive(Schema)]` on the same
///   struct is a compile error. Both traits live 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(...))]` yourself.
/// - Any pre-existing `#[cfg_attr(native, derive(Validate))]` or
///   `#[cfg_attr(native, derive(Schema))]` 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]
/// #[cfg_attr(native, derive(Schema))]
/// 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 settings fragment:
///
/// ```rust,ignore
/// #[settings(fragment = true, section = "cache")]
/// pub struct CacheSettings {
///     pub backend: 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 `#[url_patterns]` to discover resolvers 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()
}