Skip to main content

nextjson_derive/
lib.rs

1//! Zero-dependency derive macros for `nextjson`.
2//!
3//! Implemented entirely with the standard `proc_macro` API: no `syn`, no
4//! `quote`, no `proc-macro2`. The input `TokenStream` is parsed by a
5//! hand-written recursive-descent parser into a small AST, and the output is
6//! generated as text and re-parsed.
7//!
8//! ## Forward compatibility contract
9//!
10//! A derive macro only ever receives a single item's tokens, and this parser
11//! interprets a deliberately **stable grammar subset**: the item header
12//! (`struct` / `enum` + name), the generic parameter list, the `where`
13//! clause, and the field / variant structure, plus `#[njson]` /
14//! `#[nextjson]` / `#[serde]` attributes. Everything inside a field or
15//! generic *type position* is carried through verbatim as an opaque token
16//! sequence, so new Rust syntax that appears in type positions (new
17//! literals, `impl Trait` forms, associated-type paths, ...) needs no parser
18//! change — it is round-tripped unchanged.
19//!
20//! The risk of future item-level grammar changes is handled defensively:
21//! `parse_input` requires that **every** input token be consumed. If a future
22//! Rust release extends item syntax in a way this parser does not understand,
23//! the macro fails with a loud `compile_error!` naming the leftover tokens
24//! instead of silently generating impls from a mis-parsed subset.
25
26#![no_std]
27#![deny(unsafe_code)]
28#![deny(missing_docs)]
29#![doc(html_root_url = "https://docs.rs/nextjson-derive")]
30
31#[macro_use]
32extern crate alloc;
33extern crate proc_macro;
34
35use alloc::string::{String, ToString};
36use alloc::vec::Vec;
37
38use core::str::FromStr;
39use proc_macro::{Delimiter, Spacing, TokenStream, TokenTree};
40
41mod attr;
42mod case;
43mod de;
44mod schema;
45mod ser;
46
47pub(crate) use attr::{ContainerAttrs, FieldAttrs, Meta, VariantAttrs};
48
49/// Parse a string into a TokenStream.
50pub(crate) fn ts(s: &str) -> TokenStream {
51    TokenStream::from_str(s)
52        .unwrap_or_else(|e| panic!("nextjson-derive: invalid generated tokens: {e:?}"))
53}
54
55/// Build a `compile_error!` expansion from a message.
56pub(crate) fn err(msg: &str) -> TokenStream {
57    ts(&format!("::core::compile_error!({:?});", msg))
58}
59
60/// Error string returned by codegen helpers.
61pub(crate) fn err_str(msg: &str) -> String {
62    msg.to_string()
63}
64
65/// Token cursor over a slice of TokenTrees.
66pub(crate) struct P<'a> {
67    pub toks: &'a [TokenTree],
68    pub i: usize,
69}
70
71impl<'a> P<'a> {
72    pub fn peek(&self) -> Option<&TokenTree> {
73        self.toks.get(self.i)
74    }
75    pub fn next(&mut self) -> Option<TokenTree> {
76        let t = self.toks.get(self.i).cloned();
77        if t.is_some() {
78            self.i += 1;
79        }
80        t
81    }
82    pub fn is_ident(&self, s: &str) -> bool {
83        matches!(self.peek(), Some(TokenTree::Ident(id)) if id.to_string() == s)
84    }
85    pub fn is_punct(&self, ch: char) -> bool {
86        matches!(self.peek(), Some(TokenTree::Punct(p)) if p.as_char() == ch)
87    }
88    pub fn eat_ident(&mut self, s: &str) -> bool {
89        if self.is_ident(s) {
90            self.i += 1;
91            true
92        } else {
93            false
94        }
95    }
96    pub fn eat_punct(&mut self, ch: char) -> bool {
97        if self.is_punct(ch) {
98            self.i += 1;
99            true
100        } else {
101            false
102        }
103    }
104    pub fn expect_ident(&mut self) -> Option<String> {
105        match self.next() {
106            Some(TokenTree::Ident(id)) => Some(id.to_string()),
107            _ => None,
108        }
109    }
110}
111
112/// Join tokens into a re-parseable string, preserving `Joint` spacing so
113/// that punctuation sequences (`::`, `'a`, `->`, `>>`) stay adjacent.
114pub(crate) fn join(toks: &[TokenTree]) -> String {
115    let mut s = String::new();
116    let mut no_space = false;
117    for t in toks {
118        if !s.is_empty() && !no_space {
119            s.push(' ');
120        }
121        no_space = false;
122        match t {
123            TokenTree::Punct(p) => {
124                s.push_str(&p.to_string());
125                no_space = p.spacing() == Spacing::Joint;
126            }
127            _ => s.push_str(&t.to_string()),
128        }
129    }
130    s
131}
132
133/// Split tokens at a top-level separator.
134///
135/// Angle brackets are tracked so that generic types such as
136/// `BTreeMap<String, i32>` stay on a single side of the split.
137pub(crate) fn split_top(toks: &[TokenTree], sep: char) -> Vec<Vec<TokenTree>> {
138    let mut out: Vec<Vec<TokenTree>> = Vec::new();
139    let mut cur: Vec<TokenTree> = Vec::new();
140    let mut angle: usize = 0;
141    for tt in toks {
142        match tt {
143            TokenTree::Group(_) => cur.push(tt.clone()),
144            TokenTree::Punct(p) if p.as_char() == '<' => {
145                angle += 1;
146                cur.push(tt.clone());
147            }
148            TokenTree::Punct(p) if p.as_char() == '>' => {
149                angle = angle.saturating_sub(1);
150                cur.push(tt.clone());
151            }
152            TokenTree::Punct(p) if angle == 0 && p.as_char() == sep => {
153                out.push(core::mem::take(&mut cur));
154            }
155            _ => cur.push(tt.clone()),
156        }
157    }
158    if !cur.is_empty() {
159        out.push(cur);
160    }
161    if out.is_empty() {
162        out.push(Vec::new());
163    }
164    out
165}
166
167/// Read a `<...>` group. proc_macro does not group angle brackets, so this
168/// scans for the matching `>` while ignoring `->` arrow tokens.
169pub(crate) fn read_angle(p: &mut P) -> Option<Vec<TokenTree>> {
170    if !p.eat_punct('<') {
171        return None;
172    }
173    let mut depth = 1usize;
174    let mut out = Vec::new();
175    while let Some(tt) = p.next() {
176        match &tt {
177            TokenTree::Punct(c) if c.as_char() == '<' => {
178                depth += 1;
179                out.push(tt);
180            }
181            TokenTree::Punct(c)
182                if c.as_char() == '-'
183                    && matches!(p.peek(), Some(TokenTree::Punct(n)) if n.as_char() == '>') =>
184            {
185                out.push(tt);
186                out.push(p.next().unwrap());
187            }
188            TokenTree::Punct(c) if c.as_char() == '>' => {
189                if depth == 1 {
190                    return Some(out);
191                }
192                depth -= 1;
193                out.push(tt);
194            }
195            _ => out.push(tt),
196        }
197    }
198    None
199}
200
201// ---------------------------------------------------------------------------
202// AST
203// ---------------------------------------------------------------------------
204
205#[derive(Clone, Copy, PartialEq, Eq)]
206pub(crate) enum ParamKind {
207    Lifetime,
208    Type,
209    Const,
210}
211
212#[derive(Clone)]
213pub(crate) struct GenericParam {
214    pub kind: ParamKind,
215    pub full: String,
216    pub name: String,
217}
218
219#[derive(Clone, Default)]
220pub(crate) struct Generics {
221    pub params: Vec<GenericParam>,
222    pub where_preds: Vec<String>,
223}
224
225#[derive(Clone)]
226pub(crate) struct Field {
227    pub ident: Option<String>,
228    pub ty: String,
229    pub attrs: Vec<attr::Meta>,
230}
231
232#[derive(Clone)]
233pub(crate) enum Fields {
234    Unit,
235    Named(Vec<Field>),
236    Unnamed(Vec<Field>),
237}
238
239impl Fields {
240    pub fn iter(&self) -> core::slice::Iter<'_, Field> {
241        match self {
242            Fields::Unit => [].iter(),
243            Fields::Named(fields) | Fields::Unnamed(fields) => fields.iter(),
244        }
245    }
246}
247
248#[derive(Clone)]
249pub(crate) struct Variant {
250    pub ident: String,
251    pub fields: Fields,
252    pub attrs: Vec<attr::Meta>,
253}
254
255#[derive(Clone)]
256pub(crate) enum Data {
257    Struct(Fields),
258    Enum(Vec<Variant>),
259}
260
261#[derive(Clone)]
262pub(crate) struct Input {
263    pub ident: String,
264    pub generics: Generics,
265    pub data: Data,
266    pub cattr: ContainerAttrs,
267}
268
269// ---------------------------------------------------------------------------
270// Attribute collection
271// ---------------------------------------------------------------------------
272
273/// Collect leading `#[...]` attribute groups.
274fn parse_attrs(p: &mut P) -> Vec<Vec<TokenTree>> {
275    let mut out = Vec::new();
276    while p.is_punct('#') {
277        p.next();
278        if let Some(TokenTree::Group(g)) = p.next() {
279            if g.delimiter() == Delimiter::Bracket {
280                out.push(g.stream().into_iter().collect());
281            }
282        }
283    }
284    out
285}
286
287/// Extract `njson` / `nextjson` metas from a set of attribute groups.
288fn collect_metas(groups: &[Vec<TokenTree>]) -> Vec<attr::Meta> {
289    let mut out = Vec::new();
290    for g in groups {
291        out.extend(attr::metas_from_attr(g));
292    }
293    out
294}
295
296// ---------------------------------------------------------------------------
297// Top-level parse
298// ---------------------------------------------------------------------------
299
300pub(crate) fn parse_input(input: TokenStream) -> Result<Input, String> {
301    let toks: Vec<TokenTree> = input.into_iter().collect();
302    let mut p = P { toks: &toks, i: 0 };
303
304    let attrs = parse_attrs(&mut p);
305    let cattr = ContainerAttrs::from_metas(&collect_metas(&attrs));
306    eat_visibility(&mut p);
307
308    let is_enum = if p.eat_ident("struct") {
309        false
310    } else if p.eat_ident("enum") {
311        true
312    } else {
313        return Err("nextjson: expected `struct` or `enum`".into());
314    };
315
316    let ident = p
317        .expect_ident()
318        .ok_or_else(|| "nextjson: expected type name".to_string())?;
319
320    let mut generics = Generics::default();
321    if let Some(inner) = read_angle(&mut p) {
322        generics = parse_generics(&inner);
323    }
324
325    let data = if !is_enum
326        && matches!(p.peek(), Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Parenthesis)
327    {
328        let Some(TokenTree::Group(body)) = p.next() else {
329            return Err("nextjson: expected a tuple struct body".into());
330        };
331        if p.eat_ident("where") {
332            parse_where_clause(&mut p, &mut generics, false);
333        }
334        // Tuple structs terminate with `;`; consume it so the trailing-input
335        // check below sees a fully parsed item.
336        p.eat_punct(';');
337        let inner: Vec<TokenTree> = body.stream().into_iter().collect();
338        Data::Struct(Fields::Unnamed(parse_unnamed_fields(&inner)))
339    } else {
340        if p.eat_ident("where") {
341            parse_where_clause(&mut p, &mut generics, true);
342        }
343        if !is_enum {
344            match p.next() {
345                Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Brace => {
346                    let inner: Vec<TokenTree> = g.stream().into_iter().collect();
347                    Data::Struct(Fields::Named(parse_named_fields(&inner)))
348                }
349                Some(TokenTree::Punct(pc)) if pc.as_char() == ';' => Data::Struct(Fields::Unit),
350                _ => return Err("nextjson: expected a struct body".into()),
351            }
352        } else {
353            match p.next() {
354                Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Brace => {
355                    let inner: Vec<TokenTree> = g.stream().into_iter().collect();
356                    Data::Enum(parse_variants(&inner))
357                }
358                _ => return Err("nextjson: expected an enum body".into()),
359            }
360        }
361    };
362
363    // The derive input must be a single item. Any tokens left over mean the
364    // hand-written parser did not understand part of the declaration; refuse
365    // to generate code from a silently mis-parsed subset (this is the
366    // forward-compatibility guard: if a future Rust release extends item
367    // syntax, the macro fails loudly instead of emitting wrong impls).
368    if p.i != toks.len() {
369        return Err(format!(
370            "nextjson: cannot parse trailing tokens: {}",
371            join(&toks[p.i..])
372        ));
373    }
374
375    Ok(Input {
376        ident,
377        generics,
378        data,
379        cattr,
380    })
381}
382
383fn parse_where_clause(p: &mut P<'_>, generics: &mut Generics, has_braced_body: bool) {
384    let mut tokens = Vec::new();
385    while let Some(token) = p.peek() {
386        let is_body = has_braced_body
387            && p.i + 1 == p.toks.len()
388            && matches!(token, TokenTree::Group(g) if g.delimiter() == Delimiter::Brace);
389        if is_body || matches!(token, TokenTree::Punct(punct) if punct.as_char() == ';') {
390            break;
391        }
392        if let Some(token) = p.next() {
393            tokens.push(token);
394        }
395    }
396    for piece in split_top(&tokens, ',') {
397        let predicate = join(&piece).trim().to_string();
398        if !predicate.is_empty() {
399            generics.where_preds.push(predicate);
400        }
401    }
402}
403
404fn parse_generics(inner: &[TokenTree]) -> Generics {
405    let mut g = Generics::default();
406    for item in split_top(inner, ',') {
407        if item.is_empty() {
408            continue;
409        }
410        let declaration = strip_generic_default(&item);
411        let mut p = P {
412            toks: &declaration,
413            i: 0,
414        };
415        if p.is_punct('\'') {
416            p.next();
417            let name = p.expect_ident().unwrap_or_default();
418            g.params.push(GenericParam {
419                kind: ParamKind::Lifetime,
420                full: join(&declaration),
421                name: format!("'{name}"),
422            });
423        } else if p.eat_ident("const") {
424            let name = p.expect_ident().unwrap_or_default();
425            g.params.push(GenericParam {
426                kind: ParamKind::Const,
427                full: join(&declaration),
428                name,
429            });
430        } else {
431            let name = p.expect_ident().unwrap_or_default();
432            g.params.push(GenericParam {
433                kind: ParamKind::Type,
434                full: join(&declaration),
435                name,
436            });
437        }
438    }
439    g
440}
441
442fn strip_generic_default(tokens: &[TokenTree]) -> Vec<TokenTree> {
443    let mut angle_depth = 0usize;
444    for (index, token) in tokens.iter().enumerate() {
445        match token {
446            TokenTree::Punct(punct) if punct.as_char() == '<' => angle_depth += 1,
447            TokenTree::Punct(punct) if punct.as_char() == '>' => {
448                angle_depth = angle_depth.saturating_sub(1);
449            }
450            TokenTree::Punct(punct) if punct.as_char() == '=' && angle_depth == 0 => {
451                return tokens[..index].to_vec();
452            }
453            _ => {}
454        }
455    }
456    tokens.to_vec()
457}
458
459fn parse_named_fields(inner: &[TokenTree]) -> Vec<Field> {
460    split_top(inner, ',')
461        .iter()
462        .filter(|s| !s.is_empty())
463        .map(|piece| parse_named_field(piece))
464        .collect()
465}
466
467/// Consume an optional `pub` visibility specifier (`pub`, `pub(crate)`,
468/// `pub(super)`, `pub(in path)`). In the proc-macro token stream the
469/// parenthesized part arrives as a `Group` with `Parenthesis` delimiter, not
470/// as a `Punct('(')`, so it must be matched as a group.
471pub(crate) fn eat_visibility(p: &mut P<'_>) {
472    if !p.eat_ident("pub") {
473        return;
474    }
475    if matches!(p.peek(), Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Parenthesis) {
476        p.next();
477    }
478}
479
480fn parse_named_field(piece: &[TokenTree]) -> Field {
481    let mut p = P { toks: piece, i: 0 };
482    let attrs = parse_attrs(&mut p);
483    eat_visibility(&mut p);
484    // Find the field separator ':' at top level, excluding '::'.
485    let mut colon = None;
486    let mut j = p.i;
487    while j < piece.len() {
488        match &piece[j] {
489            TokenTree::Punct(c) if c.as_char() == ':' => {
490                if matches!(piece.get(j + 1), Some(TokenTree::Punct(n)) if n.as_char() == ':') {
491                    j += 2;
492                    continue;
493                }
494                colon = Some(j);
495                break;
496            }
497            _ => j += 1,
498        }
499    }
500    let (ident, ty) = match colon {
501        Some(c) => (
502            Some(join(&piece[p.i..c]).trim().to_string()),
503            join(&piece[c + 1..]).trim().to_string(),
504        ),
505        None => (None, join(&piece[p.i..]).trim().to_string()),
506    };
507    let mut field_metas = collect_metas(&attrs);
508    // `PhantomData` fields are not part of the data model (serde semantics):
509    // skip them on serialize and default them on deserialize. Normalizing at
510    // parse time keeps every codegen path (ser / de / schema) consistent.
511    if crate::schema::is_phantom_data(&ty) {
512        field_metas.push(Meta::Flag("skip".to_string()));
513    }
514    Field {
515        ident,
516        ty,
517        attrs: field_metas,
518    }
519}
520
521fn parse_unnamed_fields(inner: &[TokenTree]) -> Vec<Field> {
522    split_top(inner, ',')
523        .iter()
524        .filter(|s| !s.is_empty())
525        .map(|piece| {
526            let mut p = P { toks: piece, i: 0 };
527            let attrs = parse_attrs(&mut p);
528            eat_visibility(&mut p);
529            Field {
530                ident: None,
531                ty: join(&piece[p.i..]).trim().to_string(),
532                attrs: collect_metas(&attrs),
533            }
534        })
535        .collect()
536}
537
538fn parse_variants(inner: &[TokenTree]) -> Vec<Variant> {
539    split_top(inner, ',')
540        .iter()
541        .filter(|s| !s.is_empty())
542        .map(|piece| {
543            let mut p = P { toks: piece, i: 0 };
544            let attrs = parse_attrs(&mut p);
545            let ident = p.expect_ident().unwrap_or_default();
546            let fields = match p.next() {
547                Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Brace => {
548                    let inner2: Vec<TokenTree> = g.stream().into_iter().collect();
549                    Fields::Named(parse_named_fields(&inner2))
550                }
551                Some(TokenTree::Group(g)) if g.delimiter() == Delimiter::Parenthesis => {
552                    let inner2: Vec<TokenTree> = g.stream().into_iter().collect();
553                    Fields::Unnamed(parse_unnamed_fields(&inner2))
554                }
555                _ => Fields::Unit,
556            };
557            Variant {
558                ident,
559                fields,
560                attrs: collect_metas(&attrs),
561            }
562        })
563        .collect()
564}
565
566// ---------------------------------------------------------------------------
567// Generic helpers for code generation
568// ---------------------------------------------------------------------------
569
570/// Build `(impl_generics, ty_generics, where_clause)` for the impl header.
571pub(crate) fn build_generics(
572    input: &Input,
573    cp: &str,
574    de: bool,
575    has_flatten: bool,
576    has_borrow: bool,
577) -> (String, String, String) {
578    let g = &input.generics;
579    let c = &input.cattr;
580    let name = input.ident.clone();
581    // `remote` implements the traits for an external type; conversion bounds
582    // that mention `Self` must refer to that type instead of the mirror. The
583    // remote path already carries its generic arguments, while a local type
584    // must be written with the mirror's type parameters applied.
585    let (self_ty, remote_typed) = match &c.remote {
586        Some(r) => (r.clone(), true),
587        None => (name.clone(), false),
588    };
589
590    let mut impl_params: Vec<String> = g.params.iter().map(|p| p.full.clone()).collect();
591    if de {
592        impl_params.insert(0, "'de".to_string());
593    }
594    let impl_generics = if impl_params.is_empty() {
595        String::new()
596    } else {
597        format!("<{}>", impl_params.join(", "))
598    };
599
600    let names: Vec<String> = g.params.iter().map(|p| p.name.clone()).collect();
601    let ty_generics = if names.is_empty() {
602        String::new()
603    } else {
604        format!("<{}>", names.join(", "))
605    };
606    // The fully-instantiated `Self` for conversion bounds: for local types the
607    // type parameters must be applied (`Dst<T>`), for remote types the path
608    // already names them (`external::Foreign<T>`).
609    let self_ty_inst = if remote_typed {
610        self_ty.clone()
611    } else {
612        format!("{self_ty}{ty_generics}")
613    };
614
615    // The type's own where-clause predicates are ALWAYS required to name the
616    // type, so they are kept unconditionally. The `bound` attribute only
617    // replaces the *auto-generated per-type-parameter* bounds; serde behaves
618    // the same way.
619    let mut preds: Vec<String> = g.where_preds.clone();
620
621    let directional = if de {
622        c.bound_de.as_ref()
623    } else {
624        c.bound_ser.as_ref()
625    };
626    let bound = directional.or(c.bound.as_ref());
627    let auto_bound = |p: &GenericParam| -> Option<String> {
628        if p.kind != ParamKind::Type {
629            return None;
630        }
631        if de && has_flatten {
632            Some(format!(
633                "{0}: for<'__n> {1}::NsonDeserialize<'__n>",
634                p.name, cp
635            ))
636        } else if de {
637            Some(format!("{}: {}::NsonDeserialize<'de>", p.name, cp))
638        } else {
639            Some(format!("{}: {}::NsonSerialize", p.name, cp))
640        }
641    };
642    if let Some(bound) = bound {
643        let cleaned = bound.trim().trim_matches('"');
644        if !cleaned.is_empty() {
645            for s in cleaned.split(',') {
646                let s = s.trim();
647                if !s.is_empty() {
648                    preds.push(s.to_string());
649                }
650            }
651        }
652    } else {
653        for p in g.params.iter() {
654            if let Some(b) = auto_bound(p) {
655                preds.push(b);
656            }
657        }
658    }
659
660    // Missing-field fallbacks that call `Default::default()` must be able to
661    // name the type parameters they fall back on, so every type parameter
662    // receives a `Default` bound when any fallback can fire for a generic
663    // field. This mirrors serde, which adds `T: Default` for exactly the same
664    // attribute combinations.
665    if de && de_uses_type_param_default(input) {
666        for p in g.params.iter() {
667            if p.kind == ParamKind::Type {
668                preds.push(format!("{}: ::core::default::Default", p.name));
669            }
670        }
671    }
672
673    // Conversion attributes add their own bounds.
674    if de {
675        if let Some(from) = &c.from {
676            preds.push(format!(
677                "{from}: {cp}::NsonDeserialize<'de> + ::core::convert::Into<{self_ty_inst}>"
678            ));
679        }
680        if let Some(from) = &c.try_from {
681            preds.push(format!(
682                "{from}: {cp}::NsonDeserialize<'de> + ::core::convert::TryInto<{self_ty_inst}>"
683            ));
684            preds.push(format!(
685                "<{from} as ::core::convert::TryInto<{self_ty_inst}>>::Error: ::core::fmt::Display"
686            ));
687        }
688    } else {
689        if let Some(into) = &c.into {
690            preds.push(format!("{self_ty_inst}: ::core::clone::Clone"));
691            preds.push(format!("{self_ty_inst}: ::core::convert::Into<{into}>"));
692            preds.push(format!("{into}: {cp}::NsonSerialize"));
693            preds.push(format!("{into}: {cp}::NsonSchema"));
694        }
695    }
696
697    if de && has_borrow {
698        for p in g.params.iter() {
699            if p.kind == ParamKind::Lifetime {
700                preds.push(format!("'de: {}", p.name));
701            }
702        }
703    }
704
705    let where_clause = if preds.is_empty() {
706        String::new()
707    } else {
708        format!(" where {}", preds.join(", "))
709    };
710
711    (impl_generics, ty_generics, where_clause)
712}
713
714/// Validate attribute combinations that serde rejects at compile time.
715///
716/// Returns an error message when the combination is invalid. Called by both
717/// derive entry points so the rejection is identical regardless of which
718/// macro is expanded first.
719fn validate_input(input: &Input) -> Option<String> {
720    if let Some(name) = input.cattr.unknown.first() {
721        return Some(format!(
722            "nextjson: unsupported container attribute `{name}`; refusing to ignore wire semantics"
723        ));
724    }
725    fn unknown_field_attribute(fields: &Fields) -> Option<String> {
726        for field in fields.iter() {
727            if let Some(name) = attr::field_attrs(&field.attrs).unknown.into_iter().next() {
728                return Some(format!(
729                    "nextjson: unsupported field attribute `{name}`; refusing to ignore wire semantics"
730                ));
731            }
732        }
733        None
734    }
735    match &input.data {
736        Data::Struct(fields) => {
737            if let Some(message) = unknown_field_attribute(fields) {
738                return Some(message);
739            }
740        }
741        Data::Enum(variants) => {
742            for variant in variants {
743                if let Some(name) = attr::variant_attrs(&variant.attrs)
744                    .unknown
745                    .into_iter()
746                    .next()
747                {
748                    return Some(format!(
749                        "nextjson: unsupported variant attribute `{name}`; refusing to ignore wire semantics"
750                    ));
751                }
752                if let Some(message) = unknown_field_attribute(&variant.fields) {
753                    return Some(message);
754                }
755            }
756        }
757    }
758    // `transparent` is only meaningful on single-field structs.
759    if input.cattr.transparent {
760        match &input.data {
761            Data::Enum(_) => {
762                return Some("nextjson: `transparent` is not supported on enums".to_string());
763            }
764            Data::Struct(Fields::Named(f)) if f.len() != 1 => {
765                return Some("nextjson: `transparent` requires exactly one field".to_string());
766            }
767            Data::Struct(Fields::Unnamed(f)) if f.len() != 1 => {
768                return Some("nextjson: `transparent` requires exactly one field".to_string());
769            }
770            _ => {}
771        }
772    }
773    // `flatten` splices a nested map into the parent object, which is
774    // impossible for positional (unnamed) shapes.
775    if type_has_flag_on(input, |f, fa| fa.flatten && f.ident.is_none()) {
776        return Some(
777            "nextjson: `flatten` is not allowed on tuple structs or tuple variants".to_string(),
778        );
779    }
780    // `flatten` + `skip_serializing_if` conflicts: the decision to skip would
781    // depend on the flattened value, which serde rejects up front.
782    if type_has_flag_on(input, |_f, fa| {
783        fa.flatten && fa.skip_serializing_if.is_some()
784    }) {
785        return Some(
786            "nextjson: `flatten` cannot be combined with `skip_serializing_if`".to_string(),
787        );
788    }
789    None
790}
791
792/// Like [`type_has_flag`] but the predicate also sees the field (needed to
793/// tell named from unnamed fields).
794fn type_has_flag_on<F: Fn(&Field, &FieldAttrs) -> bool>(input: &Input, f: F) -> bool {
795    let check = |fld: &Field| f(fld, &attr::field_attrs(&fld.attrs));
796    match &input.data {
797        Data::Struct(fields) => fields.iter().any(check),
798        Data::Enum(variants) => variants.iter().any(|v| v.fields.iter().any(check)),
799    }
800}
801
802/// Emit the `NsonSchema` + `NsonSerialize` impls.
803pub(crate) fn generate_impls(input: &Input) -> TokenStream {
804    if let Some(msg) = validate_input(input) {
805        return err(&msg);
806    }
807    let cp = input.cattr.crate_path.clone();
808    let name = input.ident.clone();
809    // `remote` implements the traits for the external type itself. The remote
810    // path already names its generic arguments, so the mirror's type-generics
811    // are not appended a second time (`Foreign<T><T>` would not parse).
812    let (target, use_tg) = match &input.cattr.remote {
813        Some(r) => (r.clone(), false),
814        None => (name.clone(), true),
815    };
816    let (ig, tg, wc) = build_generics(input, &cp, false, false, false);
817    let tg_part = if use_tg { tg.as_str() } else { "" };
818    let body = if let Some(into) = &input.cattr.into {
819        // `into = "T"`: serialize by converting `self` to `T` first.
820        format!(
821            "let __v: {into} = ::core::convert::Into::into(self.clone());\n\
822             <{into} as {cp}::NsonSerialize>::nextencode(&__v, __e)"
823        )
824    } else {
825        match &input.data {
826            Data::Struct(f) => ser::serialize_struct(&name, f, input, &cp),
827            Data::Enum(v) => ser::serialize_enum(&name, v, input, &cp),
828        }
829    };
830    let out = format!(
831        "#[automatically_derived]\n\
832         impl {ig} {cp}::NsonSchema for {target}{tg_part}{wc} {{\n\
833         \x20   const SCHEMA: {cp}::TypeSchema = {schema_expr};\n\
834         }}\n\
835         #[automatically_derived]\n\
836         impl {ig} {cp}::NsonSerialize for {target}{tg_part}{wc} {{\n\
837         \x20   fn nextencode<__E: {cp}::FormatEncoder>(&self, __e: &mut __E) -> ::core::result::Result<(), __E::Error> {{\n\
838         {body}\n\
839         \x20   }}\n\
840         }}",
841        schema_expr = schema::schema_expr(input, &cp)
842    );
843    ts(&out)
844}
845
846/// Emit the `NsonDeserialize` impl.
847pub(crate) fn generate_de_impl(input: &Input) -> TokenStream {
848    if let Some(msg) = validate_input(input) {
849        return err(&msg);
850    }
851    let cp = input.cattr.crate_path.clone();
852    let name = input.ident.clone();
853    // Container-level `default` supplies missing-field values from a `Self`
854    // instance, which only makes sense for structs (serde rejects it on
855    // enums as well).
856    if matches!(&input.data, Data::Enum(_)) && input.cattr.has_default() {
857        return err("nextjson: `default` is not supported on enums");
858    }
859    let has_flatten = type_has_flag(input, |fa| fa.flatten);
860    let has_borrow = type_has_flag(input, |fa| fa.borrow);
861    if has_flatten && type_has_with(input) {
862        return err("nextjson: `flatten` cannot be combined with `with` / `deserialize_with`");
863    }
864    if has_flatten && input.cattr.deny_unknown_fields {
865        // flatten consumes every remaining key, so unknown-field rejection is
866        // silently impossible; serde rejects this combination at compile time.
867        return err("nextjson: `deny_unknown_fields` cannot be combined with `flatten`");
868    }
869    let (target, use_tg) = match &input.cattr.remote {
870        Some(r) => (r.clone(), false),
871        None => (name.clone(), true),
872    };
873    let (ig, tg, wc) = build_generics(input, &cp, true, has_flatten, has_borrow);
874    let tg_part = if use_tg { tg.as_str() } else { "" };
875    // `expecting = "..."` overrides the default `type_name`-based description
876    // used in type-mismatch and length-mismatch error messages.
877    let expecting = match &input.cattr.expecting {
878        Some(e) => format!("\n     fn expecting() -> &'static str {{ {:?} }}\n", e),
879        None => String::new(),
880    };
881    let body = if let Some(from) = &input.cattr.from {
882        // `from = "T"`: deserialize a `T` then convert into `Self`.
883        format!(
884            "let __v: {from} = <{from} as {cp}::NsonDeserialize<'de>>::nextdecode(__d)?;\n\
885             __out.write(::core::convert::Into::into(__v));\n\
886             ::core::result::Result::Ok(())"
887        )
888    } else if let Some(from) = &input.cattr.try_from {
889        // `try_from = "T"`: deserialize a `T` then fallibly convert.
890        format!(
891            "let __v: {from} = <{from} as {cp}::NsonDeserialize<'de>>::nextdecode(__d)?;\n\
892             let __c: Self = ::core::convert::TryInto::try_into(__v).map_err(|__e| {{\n\
893             \x20   {cp}::FormatError::custom({cp}::__private::ToString::to_string(&__e))\n\
894             }})?;\n\
895             __out.write(__c);\n\
896             ::core::result::Result::Ok(())"
897        )
898    } else {
899        match &input.data {
900            Data::Struct(f) => de::deserialize_struct(&name, f, input, &cp, has_flatten),
901            Data::Enum(v) => de::deserialize_enum(&name, v, input, &cp, has_flatten),
902        }
903    };
904    let out = format!(
905        "#[automatically_derived]\n\
906         impl {ig} {cp}::NsonDeserialize<'de> for {target}{tg_part}{wc} {{\n\
907         {expecting}\
908         \x20   fn nextdecode_into<__D: {cp}::FormatDecoder<'de>>(\n\
909         \x20       __d: &mut __D,\n\
910         \x20       __out: &mut {cp}::DecodeSlot<Self>,\n\
911         \x20   ) -> ::core::result::Result<(), __D::Error> {{\n\
912         \x20       __d.set_expecting(Self::expecting());\n\
913         {body}\n\
914         \x20   }}\n\
915         }}"
916    );
917    ts(&out)
918}
919
920fn type_has_flag<F: Fn(&FieldAttrs) -> bool>(input: &Input, f: F) -> bool {
921    match &input.data {
922        Data::Struct(fields) => fields.iter().any(|fld| f(&attr::field_attrs(&fld.attrs))),
923        Data::Enum(variants) => variants
924            .iter()
925            .any(|v| v.fields.iter().any(|fld| f(&attr::field_attrs(&fld.attrs)))),
926    }
927}
928
929/// Whether the generated deserializer can fall back to `Default::default()`
930/// for a field whose type is a generic parameter.
931///
932/// True when the container has a default, when any field has a bare
933/// `default` attribute, or when any field is `skip_deserializing` without an
934/// explicit `default = "path"` (which would supply its own value). Field-level
935/// `default = "path"` does not need the bound. `PhantomData` fields are
936/// excluded: `PhantomData<T>: Default` holds for every `T` with no bound.
937fn de_uses_type_param_default(input: &Input) -> bool {
938    if input.cattr.has_default() {
939        return true;
940    }
941    let mut found = false;
942    let mut scan = |f: &Field| {
943        if crate::schema::is_phantom_data(&f.ty) {
944            return;
945        }
946        let fa = attr::field_attrs(&f.attrs);
947        let bare_default = fa.default == Some(String::new());
948        let skip_without_path =
949            fa.skip_deserializing && !matches!(&fa.default, Some(d) if !d.is_empty());
950        if bare_default || skip_without_path {
951            found = true;
952        }
953    };
954    match &input.data {
955        Data::Struct(fields) => {
956            for f in fields.iter() {
957                scan(f);
958            }
959        }
960        Data::Enum(variants) => {
961            for v in variants {
962                for f in v.fields.iter() {
963                    scan(f);
964                }
965            }
966        }
967    }
968    found
969}
970
971fn type_has_with(input: &Input) -> bool {
972    type_has_flag(input, |fa| {
973        fa.with.is_some() || fa.deserialize_with.is_some()
974    })
975}
976
977// ---------------------------------------------------------------------------
978// Entry points
979// ---------------------------------------------------------------------------
980
981#[proc_macro_derive(NsonSerialize, attributes(njson, nextjson, serde))]
982/// Derive NextJson's native serialization contract and compile-time schema.
983///
984/// Configuration is accepted through `#[njson(...)]` (and, for migration
985/// convenience, `#[serde(...)]`). The generated implementation writes
986/// directly through `NsonSerialize::nextencode` and exposes
987/// `NsonSchema::SCHEMA` without depending on another macro framework.
988pub fn derive_serialize(input: TokenStream) -> TokenStream {
989    match parse_input(input) {
990        Ok(ast) => generate_impls(&ast),
991        Err(e) => err(&e),
992    }
993}
994
995#[proc_macro_derive(NsonDeserialize, attributes(njson, nextjson, serde))]
996/// Derive NextJson's native decoding contract.
997///
998/// Configuration is accepted through `#[njson(...)]` (and, for migration
999/// convenience, `#[serde(...)]`). The generated implementation decodes
1000/// through checked `DecodeSlot` state and uses normal Rust drop semantics for
1001/// partially initialized fields.
1002pub fn derive_deserialize(input: TokenStream) -> TokenStream {
1003    match parse_input(input) {
1004        Ok(ast) => generate_de_impl(&ast),
1005        Err(e) => err(&e),
1006    }
1007}
1008
1009#[cfg(test)]
1010mod tests {
1011    use super::*;
1012
1013    // The `proc_macro` API cannot be used in unit tests (it panics outside a
1014    // macro expansion), so these tests build the small AST by hand and cover
1015    // the pure logic: attribute parsing, validation, and impl-generics
1016    // construction. Parser token-level behavior is exercised by the workspace
1017    // integration tests, which compile real derives.
1018
1019    fn meta_flag(name: &str) -> Meta {
1020        Meta::Flag(name.to_string())
1021    }
1022    fn meta_named(name: &str, value: &str) -> Meta {
1023        Meta::Named(name.to_string(), value.to_string())
1024    }
1025    fn named_field(ident: &str, ty: &str, metas: Vec<Meta>) -> Field {
1026        Field {
1027            ident: Some(ident.to_string()),
1028            ty: ty.to_string(),
1029            attrs: metas,
1030        }
1031    }
1032    fn unnamed_field(ty: &str, metas: Vec<Meta>) -> Field {
1033        Field {
1034            ident: None,
1035            ty: ty.to_string(),
1036            attrs: metas,
1037        }
1038    }
1039    fn cattr(metas: &[Meta]) -> ContainerAttrs {
1040        ContainerAttrs::from_metas(metas)
1041    }
1042    fn struct_named(cattr: ContainerAttrs, fields: Vec<Field>) -> Input {
1043        Input {
1044            ident: "S".into(),
1045            generics: Generics::default(),
1046            data: Data::Struct(Fields::Named(fields)),
1047            cattr,
1048        }
1049    }
1050    fn generic_input(
1051        ident: &str,
1052        params: Vec<GenericParam>,
1053        where_preds: Vec<String>,
1054        data: Data,
1055        cattr: ContainerAttrs,
1056    ) -> Input {
1057        Input {
1058            ident: ident.to_string(),
1059            generics: Generics {
1060                params,
1061                where_preds,
1062            },
1063            data,
1064            cattr,
1065        }
1066    }
1067
1068    // -- validate_input ------------------------------------------------------
1069
1070    #[test]
1071    fn validate_rejects_transparent_enum() {
1072        let input = Input {
1073            ident: "E".into(),
1074            generics: Generics::default(),
1075            data: Data::Enum(vec![Variant {
1076                ident: "A".into(),
1077                fields: Fields::Unit,
1078                attrs: vec![],
1079            }]),
1080            cattr: cattr(&[meta_flag("transparent")]),
1081        };
1082        let msg = validate_input(&input).expect("must reject transparent enum");
1083        assert!(msg.contains("transparent"));
1084    }
1085
1086    #[test]
1087    fn validate_rejects_transparent_multi_field() {
1088        let input = struct_named(
1089            cattr(&[meta_flag("transparent")]),
1090            vec![
1091                named_field("a", "i32", vec![]),
1092                named_field("b", "i32", vec![]),
1093            ],
1094        );
1095        assert!(validate_input(&input).is_some());
1096    }
1097
1098    #[test]
1099    fn validate_rejects_flatten_on_tuple() {
1100        let input = Input {
1101            ident: "T".into(),
1102            generics: Generics::default(),
1103            data: Data::Struct(Fields::Unnamed(vec![unnamed_field(
1104                "alloc::collections::BTreeMap<String, i32>",
1105                vec![meta_flag("flatten")],
1106            )])),
1107            cattr: cattr(&[]),
1108        };
1109        let msg = validate_input(&input).expect("must reject flatten on tuple field");
1110        assert!(msg.contains("flatten"), "unexpected error: {msg}");
1111    }
1112
1113    #[test]
1114    fn validate_rejects_flatten_with_skip_if() {
1115        let input = struct_named(
1116            cattr(&[]),
1117            vec![named_field(
1118                "m",
1119                "alloc::collections::BTreeMap<String, i32>",
1120                vec![
1121                    meta_flag("flatten"),
1122                    meta_named("skip_serializing_if", "Option::is_none"),
1123                ],
1124            )],
1125        );
1126        let msg = validate_input(&input).expect("must reject flatten + skip_serializing_if");
1127        assert!(msg.contains("flatten"), "unexpected error: {msg}");
1128    }
1129
1130    #[test]
1131    fn validate_rejects_unknown_wire_attributes() {
1132        let input = struct_named(
1133            cattr(&[]),
1134            vec![named_field(
1135                "a",
1136                "i32",
1137                vec![meta_flag("not_actually_supported")],
1138            )],
1139        );
1140        let message = validate_input(&input).expect("unknown attribute must be rejected");
1141        assert!(message.contains("not_actually_supported"));
1142        assert!(message.contains("refusing to ignore"));
1143    }
1144
1145    #[test]
1146    fn validate_accepts_valid_combinations() {
1147        let ok = struct_named(
1148            cattr(&[]),
1149            vec![
1150                named_field("a", "i32", vec![]),
1151                named_field(
1152                    "m",
1153                    "alloc::collections::BTreeMap<String, i32>",
1154                    vec![meta_flag("flatten")],
1155                ),
1156            ],
1157        );
1158        assert!(validate_input(&ok).is_none());
1159
1160        let w = Input {
1161            ident: "W".into(),
1162            generics: Generics::default(),
1163            data: Data::Struct(Fields::Unnamed(vec![unnamed_field("i32", vec![])])),
1164            cattr: cattr(&[meta_flag("transparent")]),
1165        };
1166        assert!(validate_input(&w).is_none());
1167    }
1168
1169    // -- build_generics ------------------------------------------------------
1170
1171    #[test]
1172    fn build_generics_keeps_where_clause_with_bound() {
1173        // `bound` must replace only the auto bounds; the struct's own where
1174        // clause must always survive.
1175        let input = generic_input(
1176            "S",
1177            vec![GenericParam {
1178                kind: ParamKind::Type,
1179                full: "T".into(),
1180                name: "T".into(),
1181            }],
1182            vec!["T: core::fmt::Debug".into()],
1183            Data::Struct(Fields::Named(vec![named_field("v", "T", vec![])])),
1184            cattr(&[meta_named("bound", "\"T: Clone\"")]),
1185        );
1186        let (_, _, wc) = build_generics(&input, "::nextjson", false, false, false);
1187        assert!(wc.contains("Clone"), "missing user bound: {wc}");
1188        assert!(wc.contains("Debug"), "missing struct where clause: {wc}");
1189    }
1190
1191    #[test]
1192    fn build_generics_instantiates_conversion_self_type() {
1193        // Conversion bounds must name `Dst<T>`, never bare `Dst`.
1194        let input = generic_input(
1195            "Dst",
1196            vec![GenericParam {
1197                kind: ParamKind::Type,
1198                full: "T".into(),
1199                name: "T".into(),
1200            }],
1201            vec![],
1202            Data::Struct(Fields::Named(vec![named_field("x", "T", vec![])])),
1203            cattr(&[meta_named("from", "\"Src<T>\"")]),
1204        );
1205        let (_, _, wc) = build_generics(&input, "::nextjson", true, false, false);
1206        assert!(
1207            wc.contains("Into<Dst<T>>"),
1208            "missing instantiated self: {wc}"
1209        );
1210        assert!(!wc.contains("Into<Dst>"), "bare self type: {wc}");
1211    }
1212
1213    #[test]
1214    fn build_generics_adds_default_bound_for_generic_default() {
1215        // Container `default` on a generic struct must add `T: Default`.
1216        let input = generic_input(
1217            "S",
1218            vec![GenericParam {
1219                kind: ParamKind::Type,
1220                full: "T".into(),
1221                name: "T".into(),
1222            }],
1223            vec![],
1224            Data::Struct(Fields::Named(vec![named_field("v", "T", vec![])])),
1225            cattr(&[meta_flag("default")]),
1226        );
1227        let (_, _, wc) = build_generics(&input, "::nextjson", true, false, false);
1228        assert!(
1229            wc.contains("T: ::core::default::Default"),
1230            "missing Default bound: {wc}"
1231        );
1232    }
1233
1234    #[test]
1235    fn build_generics_remote_never_appends_generics_twice() {
1236        // The impl target for `remote` carries its own generic arguments.
1237        let input = generic_input(
1238            "Mirror",
1239            vec![GenericParam {
1240                kind: ParamKind::Type,
1241                full: "T".into(),
1242                name: "T".into(),
1243            }],
1244            vec![],
1245            Data::Struct(Fields::Named(vec![named_field("x", "T", vec![])])),
1246            cattr(&[meta_named("remote", "external::Foreign<T>")]),
1247        );
1248        let (_, _, wc) = build_generics(&input, "::nextjson", false, false, false);
1249        assert!(
1250            wc.contains("T: ::nextjson::NsonSerialize"),
1251            "missing auto bound: {wc}"
1252        );
1253    }
1254
1255    // -- default-bound detection ---------------------------------------------
1256
1257    #[test]
1258    fn default_bound_not_needed_for_phantom_data() {
1259        // A `PhantomData` field must not force `T: Default`.
1260        let input = struct_named(
1261            cattr(&[]),
1262            vec![
1263                named_field("_m", "core::marker::PhantomData<T>", vec![]),
1264                named_field("n", "i32", vec![]),
1265            ],
1266        );
1267        assert!(!de_uses_type_param_default(&input));
1268
1269        // With a container default the bound is required again.
1270        let input2 = struct_named(
1271            cattr(&[meta_flag("default")]),
1272            vec![named_field("v", "T", vec![])],
1273        );
1274        assert!(de_uses_type_param_default(&input2));
1275    }
1276
1277    // -- PhantomData detection ----------------------------------------------
1278
1279    #[test]
1280    fn phantom_detection_spellings() {
1281        assert!(crate::schema::is_phantom_data("PhantomData<T>"));
1282        assert!(crate::schema::is_phantom_data(
1283            "core::marker::PhantomData<T>"
1284        ));
1285        assert!(crate::schema::is_phantom_data(
1286            "::core::marker::PhantomData<T>"
1287        ));
1288        assert!(crate::schema::is_phantom_data(
1289            "core::marker::PhantomData<T>"
1290        ));
1291        assert!(!crate::schema::is_phantom_data("Vec<T>"));
1292        assert!(!crate::schema::is_phantom_data("Option<PhantomData<T>>"));
1293        assert!(!crate::schema::is_phantom_data("Phantom"));
1294    }
1295}