prismqueer_projections/

lib.rs

//! Derive macros for prism-core.
//!
//! `#[derive(Prism)]` with `#[oid("@something")]` generates:
//! - `Addressable` impl (Oid from the `@name` string, deterministic)
//! - `Display` impl (prints the `@name`)
//!
//! Field-level optic annotations generate accessor structs:
//! - `#[lens]` — total, bidirectional. Generates `FieldNameLens` with `view`/`set`.
//! - `#[prism]` — partial access. Generates `FieldNamePrism` with `extract`/`review`.
//! - `#[traversal]` — multiple targets. Generates `FieldNameTraversal` with `traverse`/`traverse_mut`.
//! - `#[iso]` — round-trip lossless. Generates `FieldNameIso` with `forward`/`backward`.
//!
//! Also generates `optic_fields()` returning `&'static [FieldOptic]` metadata.

extern crate proc_macro;

use proc_macro::TokenStream;
use proc_macro2::Span;
use quote::{format_ident, quote};
use syn::{parse_macro_input, Data, DeriveInput, Expr, Fields, Lit, Meta, Type};

// T23 (2026-06-08): the macro-reception sub-prism. Realises
// `@code/rust/macro.shim_type` per
// `mirror/shards/code/rust/macro.mirror`. The function-like
// proc-macro `declaration!{}` reads a substrate `type` declaration
// and emits the Rust struct/enum that realises it. Round-trip OID
// witness: emission is a deterministic function of the substrate
// input (the `oid_function(shim_type)` law). Per the spec's §12
// implementation cascade, this tick lands `type` only; `prism`,
// `action`, `grammar` are next cascade ticks.
mod declaration;

/// `declaration!{}` — the @code/rust/macro reception entry point.
///
/// Realises the four shims declared at
/// `mirror/shards/code/metalogue.mirror` (universal ground; the
/// 34th-instance reframe lifted the contract from per-species
/// `@code/X/macro` to `@code/metalogue`) and bound to
/// `code/rust.ast` at `mirror/shards/code/rust/macro.mirror`. Reads
/// a substrate declaration (passed as token-tree input) and emits
/// the Rust item that realises it.
///
/// # Input grammar (T23 + T24 + T25 + T26)
///
/// ```ignore
/// // T23 — `type` declarations.
/// // Record shape:
/// declaration!{ type Foo { a: u32, b: u64 } }
/// // Sum shape (closed sum of unit variants):
/// declaration!{ type Color = red | green | blue }
/// // Sum shape with parametric variants:
/// declaration!{ type Result = ok(u32) | err(u32) }
///
/// // T24 — `prism` declarations.
/// // Bare path:
/// declaration!{ prism @parse }
/// // With five-op block:
/// declaration!{
///     prism @kernel {
///         focus kernel  project kernel  split kernel
///         shift kernel  settle kernel
///     }
/// }
///
/// // T25 — `action` declarations.
/// // Substrate `action name(args) -> ret { \ }` — emits `pub fn`.
/// // Rust-altitude call site: `{ }` (empty body) per the
/// // substrate-pull seam; the shim emits `todo!()`.
/// declaration!{ action increment(x: u32) -> u32 { } }
///
/// // T26 — `grammar` declarations.
/// // Substrate `grammar @path(ext1, ext2, ...) { body }` — emits a
/// // Rust unit struct with #[derive(prismqueer::DerivePrism)] +
/// // #[oid("@path")]. Same floor as `prism`; the path IS the
/// // runtime address. Extension list and body parsed-but-not-encoded.
/// declaration!{ grammar @mirror_spec("spec") { focus project } }
/// ```
///
/// # Four laws (per spec §5)
///
/// 1. Type-soundness: emitted Rust is well-typed when the substrate
///    declaration is well-typed.
/// 2. Round-trip identity: `syn::parse2::<Item>(emission)` succeeds
///    — emission is itself a valid Rust declaration.
/// 3. OID functionality: same substrate input → byte-identical Rust
///    emission → same OID. For `prism` declarations, the runtime
///    `Addressable::oid(&Path)` equals `Oid::hash("@path".as_bytes())`
///    — the substrate path IS the runtime address.
/// 4. Substrate-pull preservation: emission references only
///    primitive Rust types and constructs already at the
///    `@code/rust` altitude (`pub struct`, `pub enum`,
///    `#[derive(prismqueer::DerivePrism)]`, primitive integer
///    types).
///
/// `action` (T25) and `grammar` (T26) declarations are supported;
/// the four-shim cascade is now total at the Rust altitude.
#[proc_macro]
pub fn declaration(input: TokenStream) -> TokenStream {
    declaration::expand(input.into()).into()
}

/// Which optic annotation a field carries.
#[derive(Clone, Copy)]
enum FieldKind {
    Lens,
    Prism,
    Traversal,
    Iso,
}

/// A field with its optic annotation.
struct AnnotatedField {
    ident: syn::Ident,
    ty: Type,
    kind: FieldKind,
}

/// Derive `Addressable`, `Display`, optic accessors, and `optic_fields()`.
///
/// # Struct-level attributes
///
/// - `#[oid("@name")]` — required. The `@name` must start with `@`.
///
/// # Field-level attributes
///
/// - `#[lens]` — total, bidirectional access. Compile error on `Option<T>`.
/// - `#[prism]` — partial access. Typically on `Option<T>` or `Result<T, E>`.
/// - `#[traversal]` — multiple targets. Typically on `Vec<T>`.
/// - `#[iso]` — round-trip lossless conversion.
/// - `#[prism(inner)]` — delegation marker (recognized, no code generated yet).
///
/// # Example
///
/// ```ignore
/// #[derive(Prism)]
/// #[oid("@claims")]
/// struct ClaimProcessor {
///     #[lens]
///     adjuster_id: u64,
///     #[prism]
///     override_reason: Option<String>,
///     #[traversal]
///     history: Vec<Event>,
/// }
/// ```
#[proc_macro_derive(Prism, attributes(oid, prism, lens, traversal, iso))]
pub fn derive_prism(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    // Extract #[oid("@something")] from struct attributes
    let oid_name = extract_oid_name(&input, "Prism");

    // Extract annotated fields from struct body
    let annotated = extract_annotated_fields(&input);

    // Validate annotations
    validate_annotations(&annotated);

    // Generate accessor structs for each annotated field
    let accessor_structs = generate_accessors(name, &annotated);

    // Generate optic_fields() metadata
    let optic_fields_impl =
        generate_optic_fields(name, &annotated, &impl_generics, &ty_generics, where_clause);

    let expanded = quote! {
        impl #impl_generics prismqueer::Addressable for #name #ty_generics #where_clause {
            fn oid(&self) -> prismqueer::Oid {
                prismqueer::Oid::hash(#oid_name.as_bytes())
            }
        }

        impl #impl_generics ::std::fmt::Display for #name #ty_generics #where_clause {
            fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
                write!(f, "{}", #oid_name)
            }
        }

        #accessor_structs

        #optic_fields_impl
    };

    TokenStream::from(expanded)
}

/// Derive `Composable`, `LambdaImpl`, `Addressable`, and `Display` for a named lambda.
///
/// # Struct-level attributes
///
/// - `#[oid("@name")]` — required. The `@name` must start with `@`.
///
/// # Generated impls
///
/// - `Addressable` — Oid from the `@name` string
/// - `Display` — prints the `@name`
/// - `LambdaImpl` — default identity body (Abs(oid, Bind(oid)))
/// - `Composable` — `.then()` composition producing `Composed<T>`
///
/// # Example
///
/// ```ignore
/// #[derive(Lambda)]
/// #[oid("@parse")]
/// pub struct Parse;
/// ```
#[proc_macro_derive(Lambda, attributes(oid))]
pub fn derive_lambda(input: TokenStream) -> TokenStream {
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    let oid_name = extract_oid_name(&input, "Lambda");

    let expanded = quote! {
        impl #impl_generics prismqueer::Addressable for #name #ty_generics #where_clause {
            fn oid(&self) -> prismqueer::Oid {
                prismqueer::Oid::hash(#oid_name.as_bytes())
            }
        }

        impl #impl_generics ::std::fmt::Display for #name #ty_generics #where_clause {
            fn fmt(&self, f: &mut ::std::fmt::Formatter<'_>) -> ::std::fmt::Result {
                write!(f, "{}", #oid_name)
            }
        }

        impl<__LambdaT: Clone + PartialEq> ::std::convert::From<#name> for prismqueer::lambda::Lambda<__LambdaT> {
            fn from(_: #name) -> prismqueer::lambda::Lambda<__LambdaT> {
                let oid = prismqueer::Oid::hash(#oid_name.as_bytes());
                prismqueer::lambda::Lambda::abs(oid.clone(), prismqueer::lambda::Lambda::bind(oid))
            }
        }

        impl<__LambdaT: Clone + PartialEq> prismqueer::lambda::Composable<__LambdaT> for #name #ty_generics #where_clause {}
    };

    TokenStream::from(expanded)
}

fn extract_oid_name(input: &DeriveInput, derive_name: &str) -> String {
    for attr in &input.attrs {
        if attr.path().is_ident("oid") {
            if let Meta::List(meta_list) = &attr.meta {
                let tokens = meta_list.tokens.clone();
                if let Ok(expr) = syn::parse2::<Expr>(tokens) {
                    if let Expr::Lit(lit) = expr {
                        if let Lit::Str(s) = &lit.lit {
                            let val = s.value();
                            if !val.starts_with('@') {
                                panic!("#[oid(\"...\")] value must start with '@', got: {:?}", val);
                            }
                            return val;
                        }
                    }
                }
            }
        }
    }
    panic!(
        "#[derive({})] requires #[oid(\"@name\")] attribute",
        derive_name
    );
}

fn extract_annotated_fields(input: &DeriveInput) -> Vec<AnnotatedField> {
    let fields = match &input.data {
        Data::Struct(data) => match &data.fields {
            Fields::Named(named) => &named.named,
            _ => return Vec::new(),
        },
        _ => return Vec::new(),
    };

    let mut annotated = Vec::new();

    for field in fields {
        let ident = match &field.ident {
            Some(id) => id.clone(),
            None => continue,
        };

        let mut kind = None;

        for attr in &field.attrs {
            if attr.path().is_ident("lens") {
                kind = Some(FieldKind::Lens);
            } else if attr.path().is_ident("prism") {
                // Distinguish #[prism] (optic) from #[prism(inner)] (delegation)
                match &attr.meta {
                    Meta::Path(_) => {
                        kind = Some(FieldKind::Prism);
                    }
                    Meta::List(_) => {
                        // #[prism(inner)] — delegation marker, skip
                    }
                    _ => {}
                }
            } else if attr.path().is_ident("traversal") {
                kind = Some(FieldKind::Traversal);
            } else if attr.path().is_ident("iso") {
                kind = Some(FieldKind::Iso);
            }
        }

        if let Some(k) = kind {
            annotated.push(AnnotatedField {
                ident,
                ty: field.ty.clone(),
                kind: k,
            });
        }
    }

    annotated
}

/// Validate optic annotations against field types.
fn validate_annotations(fields: &[AnnotatedField]) {
    for field in fields {
        match field.kind {
            FieldKind::Lens => {
                // #[lens] on Option<T> is a compile error
                if is_option_type(&field.ty) {
                    panic!(
                        "#[lens] on field `{}`: Lens is total, but Option<T> is partial. Use #[prism] instead.",
                        field.ident
                    );
                }
            }
            _ => {}
        }
    }
}

/// Check if a type is `Option<T>`.
fn is_option_type(ty: &Type) -> bool {
    if let Type::Path(type_path) = ty {
        if let Some(segment) = type_path.path.segments.last() {
            return segment.ident == "Option";
        }
    }
    false
}

/// Check if a type is `Vec<T>`.
fn is_vec_type(ty: &Type) -> bool {
    if let Type::Path(type_path) = ty {
        if let Some(segment) = type_path.path.segments.last() {
            return segment.ident == "Vec";
        }
    }
    false
}

/// Extract the inner type from `Option<T>` or `Vec<T>`.
fn extract_inner_type(ty: &Type) -> Option<&Type> {
    if let Type::Path(type_path) = ty {
        if let Some(segment) = type_path.path.segments.last() {
            if let syn::PathArguments::AngleBracketed(args) = &segment.arguments {
                if let Some(syn::GenericArgument::Type(inner)) = args.args.first() {
                    return Some(inner);
                }
            }
        }
    }
    None
}

/// Convert a snake_case field name to PascalCase for the accessor struct name.
fn to_pascal_case(s: &str) -> String {
    s.split('_')
        .filter(|part| !part.is_empty())
        .map(|part| {
            let mut chars = part.chars();
            match chars.next() {
                Some(c) => c.to_uppercase().to_string() + chars.as_str(),
                None => String::new(),
            }
        })
        .collect()
}

fn generate_accessors(
    struct_name: &syn::Ident,
    fields: &[AnnotatedField],
) -> proc_macro2::TokenStream {
    let mut tokens = proc_macro2::TokenStream::new();

    for field in fields {
        let field_ident = &field.ident;
        let field_name = field.ident.to_string();
        let pascal = to_pascal_case(&field_name);

        match field.kind {
            FieldKind::Lens => {
                let accessor_name = format_ident!("{}Lens", pascal, span = Span::call_site());
                let field_ty = &field.ty;

                tokens.extend(quote! {
                    /// Lens accessor for field `#field_name`. Total, bidirectional.
                    pub struct #accessor_name;

                    impl #accessor_name {
                        /// Get a reference to the field value.
                        pub fn view(source: &#struct_name) -> &#field_ty {
                            &source.#field_ident
                        }

                        /// Set the field value.
                        pub fn set(source: &mut #struct_name, value: #field_ty) {
                            source.#field_ident = value;
                        }
                    }

                    impl prismqueer::Named<#accessor_name> {
                        /// Create a named lens for this field.
                        pub fn lens() -> prismqueer::Named<#accessor_name> {
                            prismqueer::Named(#field_name, #accessor_name)
                        }
                    }
                });
            }
            FieldKind::Prism => {
                let accessor_name = format_ident!("{}Prism", pascal, span = Span::call_site());
                let inner_ty = extract_inner_type(&field.ty);

                if let Some(inner) = inner_ty {
                    if is_option_type(&field.ty) {
                        tokens.extend(quote! {
                            /// Prism accessor for field `#field_name`. Partial access.
                            pub struct #accessor_name;

                            impl #accessor_name {
                                /// Extract the value if present.
                                pub fn extract(source: &#struct_name) -> Option<&#inner> {
                                    source.#field_ident.as_ref()
                                }

                                /// Set the value (wraps in Some).
                                pub fn review(source: &mut #struct_name, value: #inner) {
                                    source.#field_ident = Some(value);
                                }
                            }

                            impl prismqueer::Named<#accessor_name> {
                                /// Create a named prism for this field.
                                pub fn prism() -> prismqueer::Named<#accessor_name> {
                                    prismqueer::Named(#field_name, #accessor_name)
                                }
                            }
                        });
                    } else {
                        // Non-Option prism: direct access with Option wrapping
                        let field_ty = &field.ty;
                        tokens.extend(quote! {
                            /// Prism accessor for field `#field_name`. Partial access.
                            pub struct #accessor_name;

                            impl #accessor_name {
                                /// Extract the value (always Some for non-Option types).
                                pub fn extract(source: &#struct_name) -> Option<&#field_ty> {
                                    Some(&source.#field_ident)
                                }

                                /// Set the value.
                                pub fn review(source: &mut #struct_name, value: #field_ty) {
                                    source.#field_ident = value;
                                }
                            }
                        });
                    }
                } else {
                    // Fallback for non-generic types
                    let field_ty = &field.ty;
                    tokens.extend(quote! {
                        pub struct #accessor_name;

                        impl #accessor_name {
                            pub fn extract(source: &#struct_name) -> Option<&#field_ty> {
                                Some(&source.#field_ident)
                            }

                            pub fn review(source: &mut #struct_name, value: #field_ty) {
                                source.#field_ident = value;
                            }
                        }
                    });
                }
            }
            FieldKind::Traversal => {
                let accessor_name = format_ident!("{}Traversal", pascal, span = Span::call_site());
                let field_ty = &field.ty;

                if is_vec_type(&field.ty) {
                    if let Some(inner) = extract_inner_type(&field.ty) {
                        tokens.extend(quote! {
                            /// Traversal accessor for field `#field_name`. Multiple targets.
                            pub struct #accessor_name;

                            impl #accessor_name {
                                /// Get a slice of all elements.
                                pub fn traverse(source: &#struct_name) -> &[#inner] {
                                    &source.#field_ident
                                }

                                /// Get a mutable reference to the vec.
                                pub fn traverse_mut(source: &mut #struct_name) -> &mut Vec<#inner> {
                                    &mut source.#field_ident
                                }
                            }

                            impl prismqueer::Named<#accessor_name> {
                                /// Create a named traversal for this field.
                                pub fn traversal() -> prismqueer::Named<#accessor_name> {
                                    prismqueer::Named(#field_name, #accessor_name)
                                }
                            }
                        });
                    }
                } else {
                    // Non-Vec traversal: just expose the field
                    tokens.extend(quote! {
                        pub struct #accessor_name;

                        impl #accessor_name {
                            pub fn traverse(source: &#struct_name) -> &#field_ty {
                                &source.#field_ident
                            }

                            pub fn traverse_mut(source: &mut #struct_name) -> &mut #field_ty {
                                &mut source.#field_ident
                            }
                        }
                    });
                }
            }
            FieldKind::Iso => {
                let accessor_name = format_ident!("{}Iso", pascal, span = Span::call_site());
                let field_ty = &field.ty;

                tokens.extend(quote! {
                    /// Iso accessor for field `#field_name`. Round-trip lossless.
                    pub struct #accessor_name;

                    impl #accessor_name {
                        /// Forward: get the field value.
                        pub fn forward(source: &#struct_name) -> &#field_ty {
                            &source.#field_ident
                        }

                        /// Backward: set the field value.
                        pub fn backward(source: &mut #struct_name, value: #field_ty) {
                            source.#field_ident = value;
                        }
                    }
                });
            }
        }
    }

    tokens
}

fn generate_optic_fields(
    struct_name: &syn::Ident,
    fields: &[AnnotatedField],
    impl_generics: &syn::ImplGenerics,
    ty_generics: &syn::TypeGenerics,
    where_clause: Option<&syn::WhereClause>,
) -> proc_macro2::TokenStream {
    if fields.is_empty() {
        return quote! {};
    }

    let entries: Vec<proc_macro2::TokenStream> = fields
        .iter()
        .map(|f| {
            let field_name = f.ident.to_string();
            let kind = match f.kind {
                FieldKind::Iso => quote! { prismqueer::OpticKind::Iso },
                FieldKind::Lens => quote! { prismqueer::OpticKind::Lens },
                FieldKind::Prism => quote! { prismqueer::OpticKind::Prism },
                FieldKind::Traversal => quote! { prismqueer::OpticKind::Traversal },
            };
            quote! {
                prismqueer::FieldOptic {
                    name: #field_name,
                    kind: #kind,
                }
            }
        })
        .collect();

    let count = entries.len();

    quote! {
        impl #impl_generics #struct_name #ty_generics #where_clause {
            /// Returns metadata about all optic-annotated fields.
            pub fn optic_fields() -> &'static [prismqueer::FieldOptic] {
                static FIELDS: [prismqueer::FieldOptic; #count] = [
                    #(#entries),*
                ];
                &FIELDS
            }
        }
    }
}