macros-code-review
/macros-code-review
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.
- Author
- existential-birds ↗
- Repository
- beagle ↗
- Licence
- Apache-2.0
- Last repository change
- 09.08.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 09.08.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
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.
Original author 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.
How it works
- Review Workflow
- Gates (before reporting findings)
- Output Format
- Quick Reference
- Review Checklist
- Severity Calibration
- Valid Patterns (Do NOT Flag)
SKILL.md preview
---
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 the [review-verification-protocol](../review-verification-protocol/SKILL.md) skill, including **Macro-Specific Verification** for hygiene, fragment type, and proc-macro performance claims. **Then** add findings.
## Output Format
Report findings as:
```text
[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 boundaries (vars vs types), `$crate` paths, TT-muncher pattern + recursion limits, fragment-matcher follow restrictions, decl-vs-proc decision tree | [references/declarative-macros.md](references/declarative-macros.md) |
| Proc macro types, syn/quote, span hygiene (`call_site` vs `def_site` vs `mixed_site`), `syn::Error::new_spanned` + combine, `parse_quote!` vs `quote!`, `syn` feature audit, trybuild UI tests | [references/procedural-macros.md](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::mixed_site()` is the default for introduced helper variables — `call_site` only when intentionally pointing at user code; `def_site` is nightly-only on `proc_macro::Span`
- [ ] Error reporting uses `syn::Error::new_spanned(node, msg)` with the offending AST node, never `panic!`
- [ ] Multiple errors collected and reported together via `syn::Error::combine` (good UX vs first-failure)
- [ ] `parse_quote!` (not `quote!`) used when the result needs to be a `syn::T` for further AST manipulation; `syn::parse2(quote!{...})` for fallible cases
- [ ] Public types re-exported from `proc_macro2`, not `proc_macro` (compatibility with downstream consumers)
- [ ] `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
Files in this package (3)
- SKILL.md 9 KB
- references/declarative-macros.md 12 KB
- references/procedural-macros.md 12 KB
Versions
The database has no other skills named macros-code-review.
Database snapshot: 13.11.2026 · package version bbfc9894b914 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95rust-macros
Write a macro only when a function, a trait, or a generic cannot do the job — then by-example before proc-macro, with hygiene, a `_private` helper module, and spanned compile errors instead of panics. Use when writing or reviewing macro_rules! or a proc macro, when a derive or… - 100rust-macros-metaprogramming
Use this skill when authoring declarative macro_rules! or procedural derive/attribute macros for compile-time generation in Rust. - 100rs-macros-const
Use when writing or reviewing macros, derive/proc macros, build scripts or compile-time computation — macro_rules!, declarative vs procedural macros, derive macros, attribute macros, syn/quote, hygiene, trybuild tests, cargo expand, const fn, const generics, const evaluation,… - 100rust-macros
Design, name, implement, debug, test, and review Rust declarative and procedural macros, including macro_rules matchers and repetition, hygiene, $crate paths, derive, attribute and function-like macros, proc-macro crate naming, syn parsing, quote generation, diagnostics,… - 100better-duck-macros
Proc-macro surface of the better-duck-macros crate — DuckDB user-defined functions and data derives — consumed through better-duck-core's `feature = "udf"` and `feature = "derive"` (and better-duck-diesel's `derive`), never by depending on better-duck-macros directly. Use when… - 100sasjs-core
Standards and conventions for the @sasjs/core SAS macro library (mf_*, mp_*, mm*, ms_*, mv_* macros). Use when writing or editing SAS macros in a sasjs/core-style repo, picking an existing macro over reinventing one, or the sasjs/core build, lint, doxygen, and testing conventions.