macros-code-review

name	macros-code-review
description	Reviews Rust macro code for hygiene issues, fragment misuse, compile-time impact, and procedural macro patterns. Use when reviewing macro_rules! definitions, procedural macros, derive macros, or attribute macros.

Macros Code Review

Review Workflow

1. Check Cargo.toml -- Note Rust edition (2024 reserves gen keyword, affecting macro output), proc-macro crate dependencies (syn, quote, proc-macro2), and feature flags (e.g., syn with minimal features)
2. Check macro type -- Determine if reviewing declarative (macro_rules!), function-like proc macro, attribute macro, or derive macro
3. Check if a macro is needed -- If the transformation is type-based, generics are better. Macros are for structural/repetitive code generation that generics cannot express
4. Scan macro definitions -- Read full macro bodies including all match arms, not just the invocation site
5. Check each category -- Work through the checklist below, loading references as needed
6. Gates -- Complete Gates below before reporting; do not substitute informal “I verified.”

Gates (before reporting findings)

Complete in order. Do not emit findings until Gate 4 passes for each issue.

Gate 1 — Crate context (on disk)
PASS when: You opened the reviewed crate’s Cargo.toml (workspace member path if applicable) and recorded Rust edition, whether the crate is proc-macro = true, and relevant proc-macro dependencies or syn / quote feature flags.
Blocks rationalization: Edition 2024 findings (gen, unsafe extern, generated unsafe bodies) and syn “full” vs minimal flags require this — do not flag edition-specific macro output without matching edition from the file.

Gate 2 — Macro definitions read
PASS when: For every macro you critique, you read the full definition (all macro_rules! arms, or the proc-macro entry plus helpers you rely on), not only call sites or partial expansions.
Artifact: At least one path per macro to the defining .rs file(s) you used.

Gate 3 — Per-finding evidence
PASS when: Each planned issue has [FILE:LINE] from the current tree for the macro definition, attribute/derive site, or generated code location you are discussing (not from memory, docs-only, or another branch).

Gate 4 — Pre-report protocol
PASS when: You loaded and applied beagle-rust:review-verification-protocol, including Macro-Specific Verification for hygiene, fragment type, and proc-macro performance claims. Then add findings.

Output Format

Report findings as:

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

Quick Reference

Issue Type	Reference
Fragment types, repetition, hygiene, declarative patterns	references/declarative-macros.md
Proc macro types, syn/quote, spans, testing	references/procedural-macros.md

Review Checklist

Declarative Macros (macro_rules!)

• Correct fragment types used (:expr vs :tt vs :ident -- wrong choice causes unexpected parsing)
• Repetition separators match intended syntax (, vs ; vs none, * vs +)
• Trailing comma/semicolon handled (add $(,)? or $(;)? at end of repetition)
• Matchers ordered from most specific to least specific (first match wins)
• No ambiguous expansions -- each metavariable appears in the correct repetition depth in the transcriber
• Variables defined in the macro use macro-internal names (hygiene protects variables, not types/modules/functions)
• Exported macros (#[macro_export]) use $crate:: for crate-internal paths, never crate:: or self::
• Standard library paths use ::core:: and ::alloc:: (not ::std::) for no_std compatibility
• compile_error! used for meaningful error messages on invalid input patterns
• Macro placement respects textual scoping (defined before use) unless #[macro_export]

Procedural Macros

• syn features minimized (don't enable full when derive suffices -- reduces compile time)
• Spans propagated from input tokens to output tokens (errors point to user code, not macro internals)
• Span::call_site() used for identifiers that should be visible to the caller
• Span::mixed_site() used for identifiers private to the macro (matches macro_rules! hygiene)
• Error reporting uses syn::Error with proper spans, not panic!
• Multiple errors collected and reported together via syn::Error::combine
• proc-macro2 used for testing (testable outside of compiler context)
• Generated code volume is proportionate -- proc macros that emit large amounts of code bloat compile times

Derive Macros

• Derivation is obvious -- a developer could guess what it does from the trait name alone
• Helper attributes (#[serde(skip)] style) are documented
• Trait implementation is correct for all variant shapes (unit, tuple, struct variants)
• Generated impl blocks use fully qualified paths (::core::, $crate::)

Attribute Macros

• Input item is preserved or intentionally transformed (not accidentally dropped)
• Attribute arguments are validated with clear error messages
• Test generation patterns (#[test_case] style) produce unique test names
• Framework annotations document what code they generate

Edition 2024 Awareness

• Macro output does not use gen as an identifier (reserved keyword -- use r#gen or rename)
• Generated unsafe fn bodies use explicit unsafe {} blocks around unsafe ops
• Generated extern blocks use unsafe extern

Generics vs Macros

Flag a macro when the same result is achievable with generics or trait bounds. Macros are appropriate when:

• The generated code varies structurally (not just by type)
• Repetitive trait impls for many concrete types
• Test batteries with configuration variants
• Compile-time computation that const fn cannot express

Severity Calibration

Critical (Block Merge)

• Macro generates unsound unsafe code
• Hygiene violation in macro that outputs unsafe blocks (caller's variables leak into unsafe context)
• Proc macro panics instead of returning compile_error! (crashes the compiler)
• Derive macro generates incorrect trait implementation (violates trait contract)

Major (Should Fix)

• Exported macro uses crate:: or self:: instead of $crate:: (breaks for downstream users)
• Exported macro uses ::std:: instead of ::core::/::alloc:: (breaks no_std users)
• Wrong fragment type causing unexpected parsing (:expr where :tt needed, or vice versa)
• Proc macro enables syn full features unnecessarily (compile time cost)
• Missing span propagation (errors point to macro definition, not invocation)
• No error handling in proc macro (panics on bad input instead of compile_error!)

Minor (Consider Fixing)

• Missing trailing comma/semicolon tolerance in repetition patterns
• Matcher arms not ordered most-specific-first
• Macro used where generics would be clearer and equally expressive
• Missing compile_error! fallback arm for invalid patterns
• Helper attributes undocumented

Informational (Note Only)

• Suggestions to split complex macro_rules! into a proc macro
• Suggestions to reduce generated code volume
• TT munching or push-down accumulation patterns that could be simplified

Valid Patterns (Do NOT Flag)

• macro_rules! for test batteries -- Generating repetitive test modules from a list of types/configs
• macro_rules! for trait impls -- Implementing a trait for many concrete types with identical bodies
• TT munching -- Valid advanced pattern for recursive token processing
• Push-down accumulation -- Valid pattern for building output incrementally across recursive calls
• #[macro_export] with $crate -- Correct way to make macros usable outside the defining crate
• Span::call_site() for generated functions -- Intentionally making generated items visible to callers
• syn::Error::to_compile_error() -- Correct error reporting pattern in proc macros
• trybuild tests for proc macros -- Standard compile-fail testing approach
• Attribute macros on test functions -- Common pattern for test setup/teardown
• compile_error! in impossible match arms -- Good practice for catching invalid macro input