sui_graphql_macros/

lib.rs

//! Compile-time validated macros for the Sui GraphQL API.
//!
//! Two macros, both validated against the embedded Sui GraphQL schema:
//!
//! - [`Response`] — derive macro for response types. Generates JSON
//!   deserialization from declarative field paths, catching unknown fields
//!   and type mismatches before your code runs.
//! - [`graphql_query!`] — function-style macro for query/mutation strings.
//!   Validates the source against the schema, so unknown fields, undefined
//!   variables, and bad arguments fail to compile.
//!
//! For a complete client that uses both, see
//! [`sui-graphql`](https://docs.rs/sui-graphql).
//!
//! # Quick Start
//!
//! ```no_run
//! use sui_graphql_macros::Response;
//!
//! #[derive(Response)]
//! struct ObjectData {
//!     #[field(path = "object.address")]
//!     address: String,
//!     #[field(path = "object.version")]
//!     version: u64,
//! }
//! fn main() {}
//! ```
//!
//! The macro validates that `object.address` and `object.version` exist in the schema
//! and that their types match at compile time. It then generates a
//! `from_value(serde_json::Value) -> Result<Self, String>` method, a borrowed
//! `extract(&serde_json::Value) -> Result<Self, String>` variant, and a `Deserialize`
//! implementation, so the struct can be used directly with
//! `serde_json::from_value` or as a response type in GraphQL client calls.
//!
//! # Path Syntax
//!
//! Paths use dot-separated segments with optional suffixes:
//!
//! | Syntax | Meaning | Rust Type |
//! |--------|---------|-----------|
//! | `field` | Required field | `T` |
//! | `field?` | Nullable field | `Option<T>` |
//! | `field[]` | Required list | `Vec<T>` |
//! | `field?[]` | Nullable list | `Option<Vec<T>>` |
//! | `field[]?` | List with nullable elements | `Vec<Option<T>>` |
//! | `field?[]?` | Nullable list, nullable elements | `Option<Vec<Option<T>>>` |
//!
//! Multiple `?` markers between `[]` boundaries share one `Option` wrapper.
//! Each `?` controls null tolerance at that specific segment.
//!
//! The macro enforces that path suffixes match the Rust type at compile time.
//! For example, `field?` requires `Option<T>`, and `field[]` requires `Vec<T>`.
//! A mismatch (e.g., `field?` with `String` or `field` with `Option<String>`)
//! produces a compile error.
//!
//! ## Null Handling
//!
//! ```no_run
//! use sui_graphql_macros::Response;
//!
//! #[derive(Response)]
//! struct Example {
//!     // null at `object` → error, null at `address` → error
//!     #[field(path = "object.address")]
//!     strict: String,
//!
//!     // null at `object` → Ok(None), null at `address` → Ok(None)
//!     #[field(path = "object?.address?")]
//!     flexible: Option<String>,
//!
//!     // null at `object` → Ok(None), null at `address` → error
//!     #[field(path = "object?.address")]
//!     partial: Option<String>,
//! }
//! fn main() {}
//! ```
//!
//! ## Lists
//!
//! Use `[]` to mark list fields. The macro validates this matches the schema.
//!
//! ```no_run
//! use sui_graphql_macros::Response;
//!
//! #[derive(Response)]
//! struct CheckpointDigests {
//!     #[field(path = "checkpoints.nodes[].digest")]
//!     digests: Vec<String>,
//!
//!     // Nullable list with nullable elements
//!     #[field(path = "checkpoints?.nodes?[]?.digest?")]
//!     maybe_digests: Option<Vec<Option<String>>>,
//! }
//! fn main() {}
//! ```
//!
//! ## Aliases
//!
//! Use `alias:field` when your GraphQL query uses aliases. The alias (before `:`) is the
//! JSON key used for extraction, while the field name (after `:`) is validated against
//! the schema. The alias itself is not schema-validated since it is user-defined in the
//! query.
//!
//! ```no_run
//! use sui_graphql_macros::Response;
//!
//! #[derive(Response)]
//! struct EpochCheckpoints {
//!     // GraphQL alias "firstCp" maps to schema field "checkpoints"
//!     #[field(path = "epoch.firstCp:checkpoints.nodes[].sequenceNumber")]
//!     first_checkpoints: Vec<u64>,
//! }
//! fn main() {}
//! ```
//!
//! ## Flattened Responses
//!
//! Use `#[field(flatten)]` to populate a field by passing the complete response value to
//! that field type's borrowed `extract` method. This allows response types that read from
//! the same root value to be composed without cloning it or repeating their field paths.
//! `flatten` cannot be combined with `path`.
//!
//! ```no_run
//! use sui_graphql_macros::Response;
//!
//! #[derive(Response)]
//! struct ChainInfo {
//!     #[field(path = "chainIdentifier")]
//!     chain_id: String,
//! }
//!
//! #[derive(Response)]
//! struct ResponseData {
//!     #[field(flatten)]
//!     chain: ChainInfo,
//! }
//! fn main() {}
//! ```
//!
//! ## Enums (GraphQL Unions)
//!
//! Use `#[response(root_type = "UnionType")]` on enums with newtype variants:
//!
//! ```ignore
//! #[derive(Response)]
//! #[response(root_type = "DynamicFieldValue")]
//! enum FieldValue {
//!     #[response(on = "MoveValue")]
//!     Value(MoveValueData),
//!     MoveObject(MoveObjectData), // `on` defaults to variant name
//! }
//! ```
//!
//! The macro dispatches on `__typename` in the JSON response.
//!
//! ## Attributes
//!
//! | Attribute | Level | Description |
//! |-----------|-------|-------------|
//! | `#[response(root_type = "Type")]` | struct/enum | Schema type to validate against (default: `"Query"`) |
//! | `#[response(schema = "path")]` | struct/enum | Custom schema file (relative to `CARGO_MANIFEST_DIR`) |
//! | `#[field(path = "...")]` | field | Dot-separated path with optional `?`/`[]`/alias |
//! | `#[field(flatten)]` | field | Populate by calling the field type's `extract` with the complete response value |
//! | `#[field(skip_schema_validation)]` | field | Skip compile-time schema checks for this field |
//! | `#[response(on = "TypeName")]` | variant | GraphQL `__typename` to match (default: variant name) |

extern crate proc_macro;

mod path;
mod query;
mod schema;
mod validation;

use darling::FromDeriveInput;
use darling::FromField;
use darling::FromMeta;
use darling::FromVariant;
use darling::ast::NestedMeta;
use darling::util::Flag;
use darling::util::SpannedValue;
use proc_macro::TokenStream;
use proc_macro2::TokenStream as TokenStream2;
use quote::quote;
use syn::DeriveInput;
use syn::parse_macro_input;

// ---------------------------------------------------------------------------
// Darling input structures — define the "schema" for macro input.
// Darling generates parsing code automatically, including error messages.
// ---------------------------------------------------------------------------

#[derive(Debug, FromDeriveInput)]
#[darling(attributes(response), supports(struct_named, enum_newtype))]
struct ResponseInput {
    ident: syn::Ident,
    generics: syn::Generics,
    data: darling::ast::Data<ResponseVariant, ResponseField>,
    #[darling(default)]
    schema: Option<String>,
    #[darling(default)]
    root_type: Option<SpannedValue<String>>,
}

/// A struct field (requires either `path = "..."` or `flatten`).
#[derive(Debug, FromField)]
#[darling(attributes(field))]
struct ResponseField {
    ident: Option<syn::Ident>,
    ty: syn::Type,
    #[darling(flatten)]
    options: ResponseFieldOptions,
}

#[derive(Debug)]
struct ResponseFieldOptions {
    path: Option<SpannedValue<String>>,
    flatten: Flag,
    skip_schema_validation: bool,
}

#[derive(Debug, FromMeta)]
struct ParsedResponseFieldOptions {
    path: Option<SpannedValue<String>>,
    flatten: Flag,
    #[darling(default)]
    skip_schema_validation: bool,
}

/// The inner type of a newtype enum variant.
#[derive(Debug, FromField)]
struct VariantInner {
    ty: syn::Type,
}

/// An enum variant mapping to a GraphQL union member.
#[derive(Debug, FromVariant)]
#[darling(attributes(response))]
struct ResponseVariant {
    ident: syn::Ident,
    fields: darling::ast::Fields<VariantInner>,
    /// The GraphQL type name this variant maps to (e.g., `#[response(on = "MoveValue")]`).
    /// Defaults to the variant ident if not specified.
    #[darling(default)]
    on: Option<SpannedValue<String>>,
}

impl FromMeta for ResponseFieldOptions {
    fn from_list(items: &[NestedMeta]) -> darling::Result<Self> {
        // Keep parsing and source validation errors separate so malformed input can still
        // report a missing `path`, matching Darling's required-field error accumulation.
        let mut errors = darling::Error::accumulator();
        let parsed = errors.handle(ParsedResponseFieldOptions::from_list(items));

        let path = items.iter().find_map(|item| match item {
            NestedMeta::Meta(meta) if meta.path().is_ident("path") => Some(meta),
            _ => None,
        });

        let flatten = items.iter().find_map(|item| match item {
            NestedMeta::Meta(meta) if meta.path().is_ident("flatten") => Some(meta),
            _ => None,
        });

        match (path, flatten) {
            (None, None) => errors.push(darling::Error::missing_field("path")),
            (Some(_), Some(flatten)) => errors.push(
                darling::Error::custom("`flatten` cannot be used together with `path`")
                    .with_span(flatten),
            ),
            _ => {}
        }

        errors.finish()?;
        let parsed = parsed.expect("parsed options are present when there are no errors");
        Ok(Self {
            path: parsed.path,
            flatten: parsed.flatten,
            skip_schema_validation: parsed.skip_schema_validation,
        })
    }
}

/// Derive macro for GraphQL response types with nested field extraction.
///
/// Use `#[field(path = "...")]` to specify the JSON path to extract each field.
/// Paths are dot-separated (e.g., `"object.address"` extracts `json["object"]["address"]`).
/// Use `#[field(flatten)]` to pass the complete response value to the field type's
/// borrowed `extract` method instead.
///
/// # Root Type
///
/// By default, field paths are validated against the `Query` type. Use
/// `#[response(root_type = "...")]` to validate against a different type instead.
///
/// # Generated Code
///
/// The macro generates:
/// - `from_value(serde_json::Value) -> Result<Self, String>` method
/// - `extract(&serde_json::Value) -> Result<Self, String>` borrowed method
/// - `Deserialize` implementation that uses `from_value`
///
/// # Example
///
/// ```ignore
/// // Query response (default)
/// #[derive(Response)]
/// struct ChainInfo {
///     #[field(path = "chainIdentifier")]
///     chain_id: String,
///
///     #[field(path = "epoch.epochId")]
///     epoch_id: Option<u64>,
/// }
///
/// // Mutation response
/// #[derive(Response)]
/// #[response(root_type = "Mutation")]
/// struct ExecuteResult {
///     #[field(path = "executeTransaction.effects.effectsBcs")]
///     effects_bcs: Option<String>,
/// }
/// ```
#[proc_macro_derive(Response, attributes(response, field))]
pub fn derive_query_response(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);

    match derive_query_response_impl(input) {
        Ok(tokens) => tokens.into(),
        Err(err) => err.to_compile_error().into(),
    }
}

/// Validate a GraphQL query or mutation against the embedded Sui schema at
/// compile time and return it as a `&'static str`.
///
/// One or more sources can be supplied. An inline source is a string literal;
/// prefix a path with `@` to load it from a UTF-8 file relative to the Rust
/// source file containing the macro invocation. Sources are concatenated in
/// order before the complete document is validated. File sources are terminated
/// with a newline so trailing comments cannot consume the next source; inline
/// literals are concatenated verbatim. This allows operations and fragments to
/// be kept separately:
///
/// ```ignore
/// const QUERY: &str = graphql_query!(
///     @"queries/get-chain.graphql",
///     @"queries/chain-fragment.graphql",
/// );
/// ```
///
/// On a syntactically or semantically invalid input (unknown field, wrong
/// argument type, undefined variable, etc.) the macro emits one
/// `compile_error!` per Bluejay diagnostic, so the offending call site fails to
/// build with the diagnostic text inline.
///
/// Inline inputs must be literals. A procedural macro runs before Rust name
/// resolution and therefore cannot read the value behind a path to a Rust
/// string constant while retaining compile-time GraphQL validation.
#[proc_macro]
pub fn graphql_query(input: TokenStream) -> TokenStream {
    query::expand(input)
}

fn derive_query_response_impl(input: DeriveInput) -> Result<TokenStream2, syn::Error> {
    let parsed = ResponseInput::from_derive_input(&input)?;

    // Load the GraphQL schema for validation.
    // If a custom schema path is provided, load it; otherwise use the embedded Sui schema.
    let loaded_schema = if let Some(path) = &parsed.schema {
        // Resolve path relative to the crate's directory.
        // SUI_GRAPHQL_SCHEMA_DIR is used by trybuild tests (which run from a temp directory).
        let base_dir = std::env::var("SUI_GRAPHQL_SCHEMA_DIR")
            .or_else(|_| std::env::var("CARGO_MANIFEST_DIR"))
            .unwrap();
        let full_path = std::path::Path::new(&base_dir).join(path);
        let sdl = std::fs::read_to_string(&full_path).map_err(|e| {
            syn::Error::new(
                proc_macro2::Span::call_site(),
                format!(
                    "Failed to read schema from '{}': {}",
                    full_path.display(),
                    e
                ),
            )
        })?;
        Some(schema::Schema::from_sdl(&sdl)?)
    } else {
        None
    };
    let schema = if let Some(schema) = &loaded_schema {
        schema
    } else {
        schema::Schema::load()?
    };

    // Determine root type: use specified root_type or default to "Query"
    let root_type = parsed
        .root_type
        .as_ref()
        .map(|s| s.as_str())
        .unwrap_or("Query");

    // Validate that the root type exists in the schema
    if !schema.has_type(root_type) {
        use std::fmt::Write;

        let type_names = schema.type_names();
        let suggestion = validation::find_similar(&type_names, root_type);

        let mut msg = format!("Type '{}' not found in GraphQL schema", root_type);
        if let Some(suggested) = suggestion {
            write!(msg, ". Did you mean '{}'?", suggested).unwrap();
        }

        // We only enter this block if root_type was explicitly specified (and invalid),
        // since "Query" (the default) always exists in a valid schema.
        let span = parsed.root_type.as_ref().unwrap().span();

        return Err(syn::Error::new(span, msg));
    }

    match parsed.data {
        darling::ast::Data::Struct(ref fields) => {
            generate_struct_impl(&parsed, &fields.fields, schema, root_type)
        }
        darling::ast::Data::Enum(ref variants) => {
            generate_enum_impl(&parsed, variants, schema, root_type)
        }
    }
}

/// Generate value conversion methods and `Deserialize` for a struct.
fn generate_struct_impl(
    input: &ResponseInput,
    fields: &[ResponseField],
    schema: &schema::Schema,
    root_type: &str,
) -> Result<TokenStream2, syn::Error> {
    let ident = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    // Generate extraction code for each field
    let mut field_initializers = vec![];

    for field in fields {
        let field_ident = field
            .ident
            .as_ref()
            .expect("darling ensures named fields only");

        if field.options.flatten.is_present() {
            let field_ty = &field.ty;
            field_initializers.push(quote! {
                #field_ident: <#field_ty>::extract(value)?
            });
            continue;
        }

        let spanned_path = field
            .options
            .path
            .as_ref()
            .expect("validated: non-flattened fields require a path");
        let parsed_path = path::ParsedPath::parse(spanned_path.as_str())
            .map_err(|e| syn::Error::new(spanned_path.span(), e.to_string()))?;

        let terminal_type = if !field.options.skip_schema_validation {
            Some(validation::validate_path_against_schema(
                schema,
                root_type,
                &parsed_path,
                spanned_path.span(),
            )?)
        } else {
            None
        };

        // Skip Vec excess check when schema validation is skipped (user takes full
        // responsibility) or when the terminal type is an object-like scalar (e.g., JSON)
        // whose value can be an array.
        let skip_vec_excess_check = field.options.skip_schema_validation
            || terminal_type.is_some_and(validation::is_object_like_scalar);
        validation::validate_type_matches_path(&parsed_path, &field.ty, skip_vec_excess_check)?;

        // Generate extraction code using the same parsed path
        let type_structure = validation::analyze_type(&field.ty);
        let extraction = generate_field_extraction(&parsed_path, &type_structure);
        field_initializers.push(quote! {
            #field_ident: #extraction
        });
    }

    // Generate both value conversion methods and `Deserialize`:
    //
    // - `from_value`: Owned convenience API retained for compatibility
    // - `extract`: Core extraction logic that borrows a serde_json::Value
    // - `Deserialize`: Allows direct use with serde (e.g., `serde_json::from_str::<MyStruct>(...)`)
    //   and with the GraphQL client's `query::<T>()` which requires `T: DeserializeOwned`
    Ok(quote! {
        impl #impl_generics #ident #ty_generics #where_clause {
            pub fn from_value(value: serde_json::Value) -> Result<Self, String> {
                Self::extract(&value)
            }

            pub fn extract(value: &serde_json::Value) -> Result<Self, String> {
                Ok(Self {
                    #(#field_initializers),*
                })
            }
        }

        // TODO: Implement efficient deserialization that only extracts the fields we need.
        impl<'de> serde::Deserialize<'de> for #ident #ty_generics #where_clause {
            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
            where
                D: serde::Deserializer<'de>,
            {
                let value = serde_json::Value::deserialize(deserializer)?;
                Self::from_value(value).map_err(serde::de::Error::custom)
            }
        }
    })
}

/// Generate value conversion methods and `Deserialize` for an enum (GraphQL union).
///
/// Each variant wraps a type that implements `extract`. Dispatches on `__typename`.
fn generate_enum_impl(
    input: &ResponseInput,
    variants: &[ResponseVariant],
    schema: &schema::Schema,
    root_type: &str,
) -> Result<TokenStream2, syn::Error> {
    let ident = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    let root_type_span = input
        .root_type
        .as_ref()
        .map(|s| s.span())
        .unwrap_or_else(|| ident.span());

    if !schema.is_union(root_type) {
        return Err(syn::Error::new(
            root_type_span,
            format!(
                "'{}' is not a union type. \
                 Enum Response requires root_type to be a GraphQL union",
                root_type
            ),
        ));
    }

    let mut match_arms = Vec::new();

    for variant in variants {
        let variant_ident = &variant.ident;

        // Resolve the GraphQL typename: explicit `on` or variant ident
        let graphql_typename = variant
            .on
            .as_ref()
            .map(|s| s.as_str().to_string())
            .unwrap_or_else(|| variant_ident.to_string());

        let span = variant
            .on
            .as_ref()
            .map(|s| s.span())
            .unwrap_or_else(|| variant_ident.span());

        if let Err(mut err) =
            validation::validate_union_member(schema, root_type, &graphql_typename, span)
        {
            if variant.on.is_none() {
                err.combine(syn::Error::new(
                    span,
                    "hint: use #[response(on = \"...\")] to specify a GraphQL type name different from the variant name",
                ));
            }
            return Err(err);
        }

        // Newtype variant: delegate to the inner type's borrowed parser.
        let inner_ty = &variant.fields.fields[0].ty;
        match_arms.push(quote! {
            #graphql_typename => {
                Ok(Self::#variant_ident(
                    <#inner_ty>::extract(value)?
                ))
            }
        });
    }

    let root_type_str = root_type;
    let enum_name_str = ident.to_string();

    Ok(quote! {
        impl #impl_generics #ident #ty_generics #where_clause {
            pub fn from_value(value: serde_json::Value) -> Result<Self, String> {
                Self::extract(&value)
            }

            pub fn extract(value: &serde_json::Value) -> Result<Self, String> {
                let typename = value.get("__typename")
                    .and_then(|v| v.as_str())
                    .ok_or_else(|| format!(
                        "union '{}' requires '__typename' in the response to distinguish variants. \
                         Make sure your query requests '__typename' on this field ({})",
                        #root_type_str, #enum_name_str
                    ))?;

                match typename {
                    #(#match_arms)*
                    other => Err(format!(
                        "unknown __typename '{}' for union '{}' ({})",
                        other, #root_type_str, #enum_name_str
                    )),
                }
            }
        }

        impl<'de> serde::Deserialize<'de> for #ident #ty_generics #where_clause {
            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
            where
                D: serde::Deserializer<'de>,
            {
                let value = serde_json::Value::deserialize(deserializer)?;
                Self::from_value(value).map_err(serde::de::Error::custom)
            }
        }
    })
}

/// Generate code to extract a single field from JSON using its path.
///
/// Supports multiple path formats:
/// - Simple: `"object.address"` - navigates to nested field
/// - Array: `"nodes[].name"` - iterates over array, extracts field from each element
/// - Nested arrays: `"nodes[].edges[].id"` - nested iteration, returns `Vec<Vec<T>>`
/// - Aliased: `"alias:field"` - uses alias for JSON extraction, field for validation
fn generate_field_extraction(
    path: &path::ParsedPath,
    type_structure: &validation::TypeStructure,
) -> TokenStream2 {
    let full_path = &path.raw;
    let inner = generate_from_segments(full_path, &path.segments, type_structure);
    // The inner expression returns Result<T, String>, so we use ? to unwrap
    quote! {{
        let current = value;
        #inner?
    }}
}

/// Recursively generate extraction code by traversing path segments.
///
/// For JSON extraction, uses the alias if present, otherwise uses the field name.
/// Returns code that evaluates to `Result<T, String>` (caller adds `?` to unwrap).
///
/// ## Example: `"data.nodes[].edges[].id"` with `Option<Vec<Vec<String>>>`
///
/// Each `[]` in the path corresponds to one `Vec<_>` wrapper in the type.
///
/// For `Option<_>` types, null at the outer level returns `Ok(None)`. This is achieved
/// by wrapping the extraction in a closure to capture early returns. However, once
/// inside an array iteration, the element type (`Vec<String>`) is not Optional, so
/// null values there return errors instead.
///
/// ```ignore
/// (|| {
///     // "data" (non-list) - missing/null returns None (outer Optional)
///     let current = current.get("data").unwrap_or(&serde_json::Value::Null);
///     if current.is_null() { return Ok(None); }
///
///     // "nodes[]" (list) - missing/null returns None (outer Optional)
///     let field_value = current.get("nodes").unwrap_or(&serde_json::Value::Null);
///     if field_value.is_null() { return Ok(None); }
///     let array = field_value.as_array().ok_or_else(|| "expected array")?;
///     array.iter().map(|current| {
///         // Element type: Vec<String> (not Optional, so null = error)
///
///         // "edges[]" (list) - missing/null returns Err
///         let field_value = current.get("edges").unwrap_or(&serde_json::Value::Null);
///         if field_value.is_null() { return Err("null at 'edges'"); }
///         let array = field_value.as_array().ok_or_else(|| "expected array")?;
///         array.iter().map(|current| {
///             // Element type: String (not Optional, so null = error)
///
///             // "id" (scalar) - missing/null returns Err
///             let current = current.get("id").unwrap_or(&serde_json::Value::Null);
///             if current.is_null() { return Err("null at 'id'"); }
///             serde_json::from_value(current.clone())
///         }).collect::<Result<Vec<_>, _>>()
///     }).collect::<Result<Vec<_>, _>>()
///     .map(Some)  // Wrap in Some for Option
/// })()
/// ```
fn generate_from_segments(
    full_path: &str,
    segments: &[path::PathSegment],
    type_structure: &validation::TypeStructure,
) -> TokenStream2 {
    // Step 1: Check if outer type is Optional and unwrap it
    let (is_optional, inner_type) = match type_structure {
        validation::TypeStructure::Optional(inner) => (true, inner.as_ref()),
        other => (false, other),
    };

    // Step 2: Generate core extraction code
    let core = generate_from_segments_core(full_path, segments, inner_type);

    // Step 3: Wrap Optional types in a closure so `return Ok(None)` stays local to this field.
    if is_optional {
        quote! {
            (|| {
                // Handle null elements (from `[]?`) and null top-level values
                if current.is_null() { return Ok(None) }
                #core.map(Some)
            })()
        }
    } else {
        core
    }
}

/// Core extraction logic that handles both list and non-list segments.
///
/// Each segment determines its own null behavior via `is_nullable`:
/// - `is_nullable = true` (`?` marker): null → `return Ok(None)`
/// - `is_nullable = false` (no `?`): null → `return Err(...)`
fn generate_from_segments_core(
    full_path: &str,
    segments: &[path::PathSegment],
    type_structure: &validation::TypeStructure,
) -> TokenStream2 {
    // Base case: no more segments, deserialize the current value
    let Some((segment, rest)) = segments.split_first() else {
        return quote! {
            serde_json::from_value(current.clone())
                .map_err(|e| format!("failed to deserialize '{}': {}", #full_path, e))
        };
    };

    let name = segment.field;
    // Use alias for JSON extraction if present, otherwise use field name
    let json_key = segment.json_key();

    // Generate null handling based on this segment's `?` marker
    let on_null = if segment.is_nullable {
        quote! { return Ok(None) }
    } else {
        quote! {
            return Err(format!("null value at '{}' in path '{}'", #name, #full_path))
        }
    };

    if segment.is_list() {
        // For list segments, unwrap Vector to get element type
        let element_type = match type_structure {
            validation::TypeStructure::Vector(inner) => inner.as_ref(),
            _ => unreachable!("validated: list segment requires Vec type"),
        };

        // Each array element is processed independently with its own type structure.
        // Use generate_from_segments (not _core) to handle element-level Optional.
        let rest_code = generate_from_segments(full_path, rest, element_type);

        quote! {
            // Treat missing fields as null (allows Option<T> to deserialize as None)
            let field_value = current.get(#json_key).unwrap_or(&serde_json::Value::Null);
            if field_value.is_null() {
                #on_null
            }
            let array = field_value.as_array()
                .ok_or_else(|| format!("expected array at '{}' in path '{}'", #json_key, #full_path))?;
            array.iter()
                .map(|current| { #rest_code })
                .collect::<Result<Vec<_>, String>>()
        }
    } else {
        // For non-list segments, pass type unchanged to handle nested structures
        let rest_code = generate_from_segments_core(full_path, rest, type_structure);

        quote! {
            // Treat missing fields as null (allows Option<T> to deserialize as None)
            let current = current.get(#json_key).unwrap_or(&serde_json::Value::Null);
            if current.is_null() {
                #on_null
            }
            #rest_code
        }
    }
}