feat: added macro for auto registration

Author: raphael-goetz

rust/hercules-macros/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "hercules-macros"
+description = "Attribute macros for the hercules action SDK"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lib]
+proc-macro = true
+
+[dependencies]
+syn = { version = "2", features = ["full", "extra-traits"] }
+quote = "1"
+proc-macro2 = "1"

rust/hercules-macros/src/data_type.rs

@@ -0,0 +1,41 @@
+use proc_macro2::TokenStream;
+use quote::quote;
+use syn::ItemStruct;
+
+use crate::parse::{hercules_path, translation_vec, AttrArgs};
+
+pub fn expand(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
+    let item_struct: ItemStruct = syn::parse2(item)?;
+    let args = AttrArgs::parse(attr)?;
+    let hercules = hercules_path();
+
+    let identifier = args.required_string("identifier")?;
+    let name = translation_vec(&args.translations("name")?, &hercules);
+    let display_message = translation_vec(&args.translations("display_message")?, &hercules);
+    let alias = translation_vec(&args.translations("alias")?, &hercules);
+    let generic_keys: Vec<String> = args.string_list("generic_keys")?;
+
+    let ident = &item_struct.ident;
+    Ok(quote! {
+        #item_struct
+
+        impl #hercules::DataType for #ident {
+            fn meta() -> #hercules::DataTypeMeta {
+                #hercules::DataTypeMeta {
+                    identifier: #identifier.to_string(),
+                    name: #name,
+                    display_message: #display_message,
+                    alias: #alias,
+                    generic_keys: vec![#(#generic_keys.to_string()),*],
+                }
+            }
+        }
+
+        #hercules::inventory::submit! {
+            #hercules::Registration(|action| {
+                action.register_data_type::<#ident>()
+                    .unwrap_or_else(|e| panic!("failed to register data type {}: {e}", stringify!(#ident)));
+            })
+        }
+    })
+}

rust/hercules-macros/src/event.rs

@@ -0,0 +1,71 @@
+use proc_macro2::{Span, TokenStream};
+use quote::quote;
+use syn::ItemStruct;
+
+use crate::items::setting_tokens;
+use crate::parse::{
+    hercules_path, optional_string, optional_translation_vec, take_repeated, AttrArgs,
+};
+
+pub fn expand(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
+    let mut item_struct: ItemStruct = syn::parse2(item)?;
+    let args = AttrArgs::parse(attr)?;
+    let hercules = hercules_path();
+
+    let base = args.path("base")?.ok_or_else(|| {
+        syn::Error::new(
+            Span::call_site(),
+            "missing required `base = SomeRuntimeEvent`",
+        )
+    })?;
+
+    let settings = take_repeated(&mut item_struct, "setting")?
+        .iter()
+        .map(|s| setting_tokens(s, &hercules))
+        .collect::<syn::Result<Vec<_>>>()?;
+
+    let identifier = optional_string(args.string("identifier"))?;
+    let signature = optional_string(args.string("signature"))?;
+    let name = optional_translation_vec(&args, "name", &hercules)?;
+    let description = optional_translation_vec(&args, "description", &hercules)?;
+    let documentation = optional_translation_vec(&args, "documentation", &hercules)?;
+    let display_message = optional_translation_vec(&args, "display_message", &hercules)?;
+    let alias = optional_translation_vec(&args, "alias", &hercules)?;
+    let display_icon = optional_string(args.string("display_icon"))?;
+    let editable = if args.flag("editable") {
+        quote!(Some(true))
+    } else {
+        quote!(None)
+    };
+
+    let ident = &item_struct.ident;
+    Ok(quote! {
+        #item_struct
+
+        impl #hercules::Event for #ident {
+            type Base = #base;
+
+            fn meta() -> #hercules::EventMeta {
+                #hercules::EventMeta {
+                    identifier: #identifier,
+                    signature: #signature,
+                    settings: vec![#(#settings),*],
+                    editable: #editable,
+                    name: #name,
+                    description: #description,
+                    documentation: #documentation,
+                    display_message: #display_message,
+                    alias: #alias,
+                    display_icon: #display_icon,
+                }
+            }
+        }
+
+        #hercules::inventory::submit! {
+            #hercules::Registration(|action| {
+                action.register_event::<#ident>()
+                    .unwrap_or_else(|e| panic!("failed to register event {}: {e}", stringify!(#ident)));
+            })
+        }
+    })
+}

rust/hercules-macros/src/function.rs

@@ -0,0 +1,80 @@
+use proc_macro2::{Span, TokenStream};
+use quote::quote;
+use syn::ItemStruct;
+
+use crate::items::parameter_tokens;
+use crate::parse::{
+    hercules_path, optional_string, optional_translation_vec, take_repeated, AttrArgs,
+};
+
+pub fn expand(attr: TokenStream, item: TokenStream) -> syn::Result<TokenStream> {
+    let mut item_struct: ItemStruct = syn::parse2(item)?;
+    let args = AttrArgs::parse(attr)?;
+    let hercules = hercules_path();
+
+    let base = args.path("base")?.ok_or_else(|| {
+        syn::Error::new(
+            Span::call_site(),
+            "missing required `base = SomeRuntimeFunction`",
+        )
+    })?;
+
+    let parameters = take_repeated(&mut item_struct, "parameter")?
+        .iter()
+        .map(|p| parameter_tokens(p, &hercules))
+        .collect::<syn::Result<Vec<_>>>()?;
+
+    let identifier = optional_string(args.string("identifier"))?;
+    let signature = optional_string(args.string("signature"))?;
+    let name = optional_translation_vec(&args, "name", &hercules)?;
+    let description = optional_translation_vec(&args, "description", &hercules)?;
+    let documentation = optional_translation_vec(&args, "documentation", &hercules)?;
+    let deprecation_message = optional_translation_vec(&args, "deprecation_message", &hercules)?;
+    let display_message = optional_translation_vec(&args, "display_message", &hercules)?;
+    let alias = optional_translation_vec(&args, "alias", &hercules)?;
+    let display_icon = optional_string(args.string("display_icon"))?;
+    let design = optional_string(args.string("design"))?;
+    // Presence-only: this overrides `throws_error` to `true`; to leave it
+    // unset (inherit the base), simply omit the flag.
+    let throws_error = if args.flag("throws_error") {
+        quote!(Some(true))
+    } else {
+        quote!(None)
+    };
+
+    let ident = &item_struct.ident;
+    Ok(quote! {
+        #item_struct
+
+        impl #hercules::Function for #ident {
+            type Base = #base;
+
+            fn meta() -> #hercules::FunctionMeta {
+                #hercules::FunctionMeta {
+                    identifier: #identifier,
+                    signature: #signature,
+                    name: #name,
+                    description: #description,
+                    documentation: #documentation,
+                    deprecation_message: #deprecation_message,
+                    display_message: #display_message,
+                    alias: #alias,
+                    display_icon: #display_icon,
+                    design: #design,
+                    throws_error: #throws_error,
+                    parameters: vec![#(#parameters),*],
+                }
+            }
+        }
+
+        // `Function` carries no instance/state (dispatch always resolves
+        // through `Base`), so unlike `runtime_function` this needs no
+        // `manual` escape hatch — it's always safe to auto-register.
+        #hercules::inventory::submit! {
+            #hercules::Registration(|action| {
+                action.register_function::<#ident>()
+                    .unwrap_or_else(|e| panic!("failed to register function {}: {e}", stringify!(#ident)));
+            })
+        }
+    })
+}

rust/hercules-macros/src/items.rs

@@ -0,0 +1,67 @@
+//! Token builders for the two repeatable child items:
+//! `#[parameter(...)]` (functions) and `#[setting(...)]` (events).
+
+use proc_macro2::TokenStream;
+use quote::quote;
+
+use crate::parse::{translation_vec, AttrArgs};
+
+pub fn parameter_tokens(args: &AttrArgs, hercules: &TokenStream) -> syn::Result<TokenStream> {
+    let runtime_name = args.required_string("runtime_name")?;
+    let runtime_definition_name = match args.string("runtime_definition_name")? {
+        Some(s) => quote!(Some(#s.to_string())),
+        None => quote!(None),
+    };
+    let name = translation_vec(&args.translations("name")?, hercules);
+    let description = translation_vec(&args.translations("description")?, hercules);
+    let documentation = translation_vec(&args.translations("documentation")?, hercules);
+    let default_value = match args.value_tokens("default_value")? {
+        Some(v) => quote!(Some(#hercules::serde_json::json!(#v))),
+        None => quote!(None),
+    };
+    let hidden = args.flag("hidden");
+    let optional = args.flag("optional");
+
+    Ok(quote! {
+        #hercules::ParameterMeta {
+            runtime_name: #runtime_name.to_string(),
+            runtime_definition_name: #runtime_definition_name,
+            name: #name,
+            description: #description,
+            documentation: #documentation,
+            default_value: #default_value,
+            hidden: #hidden,
+            optional: #optional,
+        }
+    })
+}
+
+pub fn setting_tokens(args: &AttrArgs, hercules: &TokenStream) -> syn::Result<TokenStream> {
+    let identifier = args.required_string("identifier")?;
+    let unique = match args.string("unique")?.as_deref() {
+        Some("project") => quote!(#hercules::UniquenessScope::Project),
+        _ => quote!(#hercules::UniquenessScope::None),
+    };
+    let linked: Vec<String> = args.string_list("linked_data_type_identifiers")?;
+    let name = translation_vec(&args.translations("name")?, hercules);
+    let description = translation_vec(&args.translations("description")?, hercules);
+    let default_value = match args.value_tokens("default_value")? {
+        Some(v) => quote!(Some(#hercules::serde_json::json!(#v))),
+        None => quote!(None),
+    };
+    let hidden = args.flag("hidden");
+    let optional = args.flag("optional");
+
+    Ok(quote! {
+        #hercules::EventSettingMeta {
+            identifier: #identifier.to_string(),
+            unique: #unique,
+            linked_data_type_identifiers: vec![#(#linked.to_string()),*],
+            default_value: #default_value,
+            name: #name,
+            description: #description,
+            hidden: #hidden,
+            optional: #optional,
+        }
+    })
+}

rust/hercules-macros/src/lib.rs

@@ -0,0 +1,64 @@
+//! Attribute macros that replace the TS SDK's `reflect-metadata` decorators
+//! (`@Identifier`, `@Signature`, `@Parameter`, ...) with compile-time code
+//! generation: each macro parses its arguments and any repeated
+//! `#[parameter(...)]`/`#[setting(...)]` helper attributes on the annotated
+//! struct, then emits a `meta()` associated function implementing the
+//! corresponding `hercules` trait. No runtime reflection, no metadata
+//! registry — the definition is just a value the macro builds once, at
+//! compile time.
+
+mod data_type;
+mod event;
+mod function;
+mod items;
+mod parse;
+mod runtime_event;
+mod runtime_function;
+
+use proc_macro::TokenStream;
+
+fn run(
+    f: impl FnOnce(
+        proc_macro2::TokenStream,
+        proc_macro2::TokenStream,
+    ) -> syn::Result<proc_macro2::TokenStream>,
+    attr: TokenStream,
+    item: TokenStream,
+) -> TokenStream {
+    f(attr.into(), item.into())
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+/// Declares a function Aquila can invoke. See the crate-level docs on
+/// `hercules::RuntimeFunction` for the full attribute grammar.
+#[proc_macro_attribute]
+pub fn runtime_function(attr: TokenStream, item: TokenStream) -> TokenStream {
+    run(runtime_function::expand, attr, item)
+}
+
+/// Declares a public [`hercules::Function`] that overrides metadata on top
+/// of a `base = SomeRuntimeFunction`.
+#[proc_macro_attribute]
+pub fn function(attr: TokenStream, item: TokenStream) -> TokenStream {
+    run(function::expand, attr, item)
+}
+
+/// Declares a data type derived from the struct's `schemars::JsonSchema` impl.
+#[proc_macro_attribute]
+pub fn data_type(attr: TokenStream, item: TokenStream) -> TokenStream {
+    run(data_type::expand, attr, item)
+}
+
+/// Declares an internal event/flow-type an action can fire.
+#[proc_macro_attribute]
+pub fn runtime_event(attr: TokenStream, item: TokenStream) -> TokenStream {
+    run(runtime_event::expand, attr, item)
+}
+
+/// Declares a public [`hercules::Event`] that overrides metadata on top of a
+/// `base = SomeRuntimeEvent`.
+#[proc_macro_attribute]
+pub fn event(attr: TokenStream, item: TokenStream) -> TokenStream {
+    run(event::expand, attr, item)
+}