Add compiler-macros crate for parser development macros

Introduces the new `compiler-macros` crate to the workspace.

This crate provides procedural macros designed to simplify and
reduce boilerplate for common patterns used throughout the new
parser implementation. By abstracting away repetitive logic,
this macros make the parser's components cleaner and easier
to maintain.

Author: mkpro118

Cargo.lock

@@ -4,3 +4,4 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
+compiler-macros = { path = "./compiler_macros" }

Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "compiler-macros"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = "1.0"
+quote = "1.0"
+syn = { version = "2.0", features = ["full"] }

compiler_macros/Cargo.lock

@@ -0,0 +1,72 @@
+# Simple Builder Proc-Macro PRD
+
+## 1. Objective
+
+To provide a simple and ergonomic solution for creating builder patterns in Rust. This proc-macro will automate the generation of a basic builder, reducing boilerplate code for simple use cases.
+
+## 2. Background
+
+The builder pattern is a useful way to construct complex objects. However, writing the builder struct and its methods can be tedious. This proc-macro automates the creation of a simple builder.
+
+## 3. User Persona
+
+This tool is for Rust developers who want a quick and easy way to create a builder for their structs without the complexity of a full type-state implementation.
+
+## 4. API Definition
+
+The public API will consist of a single derive macro:
+
+```rust
+use simple_builder::SimpleBuilder;
+
+#[derive(SimpleBuilder, Default)]
+#[builder_name = "MyCustomBuilderName"] // Optional: to rename the builder struct
+pub struct MyStruct {
+    // ... fields
+}
+```
+
+-   `#[derive(SimpleBuilder)]`: The main entry point. It will trigger the builder generation.
+-   `#[builder_name = "..."]` (optional attribute): Allows the user to specify a custom name for the generated builder struct. If not provided, it will default to `[StructName]Builder`.
+
+### Constraints
+
+-   The target struct **must** implement the `Default` trait.
+
+## 5. Requirements & Features
+
+### 5.1. "With Defaults" Builder Logic
+
+The builder will follow a "with defaults" strategy. This means:
+
+-   The `build()` method can be called at any time.
+-   If a field has been set using its `with_...` method, the builder will use that value.
+-   If a field has not been set, the builder will use the value from the struct's `Default` implementation.
+
+### 5.2. Generated Code
+
+The macro will generate:
+
+1.  A public `...Builder` struct with `Option` fields.
+2.  A `new()` method to create an empty builder.
+3.  A `with_<field_name>()` method for each field in the target struct.
+4.  A `build()` method that constructs the target struct, intelligently combining user-provided values with default values.
+
+## 6. Acceptance Criteria
+
+To consider this feature complete and correct, the following criteria must be met:
+
+1.  **Compilation:** A struct decorated with `#[derive(SimpleBuilder, Default)]` must compile successfully.
+2.  **Builder Generation:** The corresponding `...Builder` struct must be generated and be publicly accessible.
+3.  **`new()` Method:** The `...Builder::new()` method must exist and return a new builder instance.
+4.  **`with_...` Methods:** Each field in the target struct must have a corresponding `with_<field_name>()` method on the builder.
+5.  **`build()` Method:** The `build()` method must be callable on the builder at any time.
+6.  **Correctness (Set Fields):** When a field is set via its `with_...` method, the `build()` method must produce a struct with that exact value for that field.
+7.  **Correctness (Unset Fields):** When a field is not set, the `build()` method must produce a struct where that field has the value from the `Default` implementation.
+
+## 7. Out of Scope (Future Work)
+
+-   **Type-State Builder:** A more advanced builder that uses the type-state pattern to enforce compile-time correctness.
+-   **Generic Structs:** Support for structs with generic parameters.
+-   **Required Fields:** An attribute to mark certain fields as required.
+-   **Validation:** Adding validation logic to the `build()` method.

compiler_macros/Cargo.toml

@@ -0,0 +1,188 @@
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{Data, DeriveInput, Fields, parse_macro_input};
+
+/// Derive macro for implementing `AstNode` as a leaf node (non-container).
+///
+/// This automatically implements `HasSpan`, `HasNodeType`, and `AstNode` with
+/// `is_container() = false`.
+///
+/// Requires a `span` field of type `SymbolSpan`.
+///
+/// # Example
+///
+/// ```rust
+/// #[derive(AstLeafNode)]
+/// struct StringLit {
+///     pub value: String,
+///     pub span: SymbolSpan,
+/// }
+/// ```
+#[proc_macro_derive(AstLeafNode)]
+pub fn derive_ast_leaf_node(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    let name = &input.ident;
+    let generics = input.generics.clone();
+    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+    // Verify the struct has a `span` field
+    let has_span_field = match &input.data {
+        Data::Struct(data_struct) => match &data_struct.fields {
+            Fields::Named(fields) => fields.named.iter().any(|field| {
+                field.ident.as_ref().is_some_and(|ident| ident == "span")
+            }),
+            _ => false,
+        },
+        _ => false,
+    };
+
+    if !has_span_field {
+        return syn::Error::new_spanned(
+            &input,
+            "AstLeafNode can only be derived for structs with a `span: SymbolSpan` field"
+        ).to_compile_error().into();
+    }
+
+    let type_name = name.to_string();
+
+    let expanded = quote! {
+        impl #impl_generics HasSpan for #name #ty_generics #where_clause {
+            fn span(&self) -> &SymbolSpan {
+                &self.span
+            }
+        }
+
+        impl #impl_generics HasNodeType for #name #ty_generics #where_clause {
+            fn node_type(&self) -> &'static str {
+                #type_name
+            }
+        }
+
+        impl #impl_generics AstNode for #name #ty_generics #where_clause {}
+
+        impl #impl_generics AstVisitable for #name #ty_generics #where_clause {}
+    };
+
+    TokenStream::from(expanded)
+}
+
+/// Derive macro for implementing `AstNode` as a container node.
+///
+/// This automatically implements `HasSpan`, `HasNodeType`, and `AstNode` with
+/// `is_container() = true`.
+///
+/// Requires a `span` field of type `SymbolSpan`.
+/// The `accept` method should be implemented manually for visiting children.
+///
+/// # Example
+///
+/// ```rust
+/// #[derive(AstContainerNode)]
+/// struct ModelDecl {
+///     pub name: Ident,
+///     pub members: Vec<ModelMember>,
+///     pub span: SymbolSpan,
+/// }
+/// ```
+#[proc_macro_derive(AstContainerNode)]
+pub fn derive_ast_container_node(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    let name = &input.ident;
+    let generics = input.generics.clone();
+    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
+
+    // Verify the struct has a `span` field
+    let has_span_field = match &input.data {
+        Data::Struct(data_struct) => match &data_struct.fields {
+            Fields::Named(fields) => fields.named.iter().any(|field| {
+                field.ident.as_ref().is_some_and(|ident| ident == "span")
+            }),
+            _ => false,
+        },
+        _ => false,
+    };
+
+    if !has_span_field {
+        return syn::Error::new_spanned(
+            &input,
+            "AstContainerNode can only be derived for structs with a `span: SymbolSpan` field"
+        ).to_compile_error().into();
+    }
+
+    let type_name = name.to_string();
+
+    let expanded = quote! {
+        impl #impl_generics HasSpan for #name #ty_generics #where_clause {
+            fn span(&self) -> &SymbolSpan {
+                &self.span
+            }
+        }
+
+        impl #impl_generics HasNodeType for #name #ty_generics #where_clause {
+            fn node_type(&self) -> &'static str {
+                #type_name
+            }
+        }
+
+        impl #impl_generics AstNode for #name #ty_generics #where_clause {
+            fn is_container(&self) -> bool {
+                true
+            }
+        }
+
+        impl #impl_generics AstVisitable for #name #ty_generics #where_clause {}
+    };
+
+    TokenStream::from(expanded)
+}
+
+/// Derive an inherent `name()` method for an enum that returns the variant name.
+///
+/// For unit variants, the match arm uses `Type::Variant`.
+/// For tuple variants, it uses `Type::Variant(..)`.
+/// For struct variants, it uses `Type::Variant { .. }`.
+///
+/// # Example
+///
+/// ```rust
+/// #[derive(EnumKindName)]
+/// enum K { Unit, Tuple(u8), Struct { x: u8 } }
+/// # impl K { /* name() generated */ }
+/// ```
+#[proc_macro_derive(EnumKindName)]
+pub fn derive_enum_kind_name(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    let name = &input.ident;
+
+    let Data::Enum(data_enum) = &input.data else {
+        return syn::Error::new_spanned(
+            &input,
+            "EnumKindName can only be derived for enums",
+        )
+        .to_compile_error()
+        .into();
+    };
+
+    let arms = data_enum.variants.iter().map(|v| {
+        let v_ident = &v.ident;
+        let v_name = v_ident.to_string();
+        match &v.fields {
+            Fields::Unit => quote! { #name::#v_ident => #v_name },
+            Fields::Unnamed(_) => quote! { #name::#v_ident(..) => #v_name },
+            Fields::Named(_) => quote! { #name::#v_ident { .. } => #v_name },
+        }
+    });
+
+    let expanded = quote! {
+        impl #name {
+            /// Return the enum variant name.
+            pub fn name(&self) -> &'static str {
+                match self {
+                    #( #arms, )*
+                }
+            }
+        }
+    };
+
+    TokenStream::from(expanded)
+}