RFC: Diagnostic API style — template directives vs inline macros

[aacebo]

Diagnostic API

We're evaluating two approaches for emitting compile-time diagnostics (errors, warnings, notes) from #[zyn::element] functions.

Option A: Template directives (@throw, @warn, @note, @help)

Diagnostics live inside zyn! templates as @-directives:

#[zyn::element]
fn validated(name: Extract<Ident>) -> zyn::TokenStream {
    zyn::zyn! {
        @if (name.to_string() == "forbidden") {
            @throw "reserved identifier" {
                @note "this name is reserved by the compiler"
                @help "try a different name like `my_handler`"
            }
        } @else {
            fn {{ name }}() {}
        }
    }
}

• Declarative — diagnostics are part of the template DSL
• @throw halts expansion immediately
• @note and @help nest inside @throw / @warn
• String literals only (no format args)

Option B: Inline macros (error!, warn!, note!, help!, bail!)

Diagnostics are plain Rust macro calls in the element body:

#[zyn::element]
fn validated(name: Extract<Ident>) -> zyn::TokenStream {
    if name.to_string() == "forbidden" {
        error!("reserved identifier"; span = name.span());
        note!("this name is reserved by the compiler");
        help!("try a different name like `my_handler`");
    }
    bail!();

    zyn::zyn! { fn {{ name }}() {} }
}

• Imperative — diagnostics use normal Rust control flow
• bail!() returns early only if errors accumulated
• format!-style args: error!("field \{}` missing", name)`
• Explicit span control: error!("msg"; span = ident.span())

Side-by-side: multiple errors

Option A:

zyn::zyn! {
    @for (field in fields) {
        @if (!field.is_valid()) {
            @throw "invalid field" {
                @note "only named fields are supported"
            }
        }
    }
}

Option B:

for field in &fields {
    if !field.is_valid() {
        error!("invalid field `{}`", field.ident; span = field.span());
        note!("only named fields are supported");
    }
}
bail!();

zyn::zyn! { ... }

Key difference: Option A halts on the first @throw. Option B accumulates all errors and reports them together with bail!().

---

Feel free to comment with additional thoughts!

[werifu]

I prefer macros since it looks more natural for a Rust developer. However, I feel the sequential calls of macros are not united, in which case I think it's better to group them into a block just like Option A.

e.g. It can be:

error!{
"msg";
 span!();
 note!();
 help!() 
}

And the inner diagnostics can be represented in any order.

[aacebo]

good to know thanks for the feedback