feat: add TokenStream snapshot support

[gaetschwartz]

Summary

Adds a new tokenstream feature (disabled by default) that enables snapshot testing of proc_macro2::TokenStream values:

• New assert_token_snapshot! macro accepting any ToTokens type
• File-based mode: pretty-prints using prettier-please, falls back to TokenStream::to_string() with a warning
• Inline mode with @{ ... } brace syntax for semantic token comparison
• format_tokens setting to disable pretty-printing
• cargo-insta extended to detect and preserve @{ ... } brace format during updates
• Doc attribute whitespace normalization for stable inline round-trips

Usage

// File-based
assert_token_snapshot!(tokens);

// Inline with semantic comparison
assert_token_snapshot!(tokens, @{ struct Foo; });

// Multiline
assert_token_snapshot!(tokens, @{
    fn hello() {
        println!("world");
    }
});

New dependencies (all optional, gated behind tokenstream feature)

• syn (full, visit-mut)
• quote
• prettier-please
• proc-macro2

Test plan

• 125 unit tests pass (cargo nextest run --features tokenstream -p insta)
• 845 lines of functional tests covering: inline update, matching, file-based, semantic comparison, multiline, format_tokens disabled, compile-time errors for invalid content, ToTokens acceptance, non-expression fallback
• CI passes on all targets

[max-sixty]

we generally avoid having macros for types; instead we have them for formsts. what's the advantage of this vs serializing to yaml?

[gaetschwartz]

what's the advantage of this vs serializing to yaml?

The types you'd snapshot with this macro (e.g. syn::DeriveInput, custom AST nodes, etc.) don't implement serde::Serialize — they live in the proc-macro2/syn ecosystem, not serde. So serializing to YAML isn't an option. The macro works with any type that implements quote::ToTokens/syn::Parse, just like assert_yaml_snapshot! works with any type that implements serde::Serialize.

we generally avoid having macros for types; instead we have them for formsts.

I'd argue this actually is a format macro. The conversion to/from proc_macro2::TokenStream via quote::ToTokens/syn::Parse (and by extension to/from string) is a serialization format, just like serde's conversion to/from YAML/JSON. The macro snapshots any type that implements those traits — it's not specific to one type.

[max-sixty]

Yes, I think that's a reasonable argument.

But what is the boundary condition?

This could be a separate project? I'd be happy to link there. Or if there's a substantial following over time, we could consider adding it to the main project; that would at least help alleviate the additional support burden...