feat(stackable-versioned): Add argument to hint for wrapped types (#1089)

* feat(stackable-versioned): Add argument to hint for wrapped types

* docs: Update doc comments

Co-authored-by: Nick <[email protected]>

* chore: Add changelog entry

---------

Co-authored-by: Nick <[email protected]>

Author: Techassi

crates/stackable-versioned-macros/src/attrs/item/field.rs

@@ -1,4 +1,4 @@
-use darling::{Error, FromField, Result, util::Flag};
+use darling::{Error, FromField, FromMeta, Result, util::Flag};
 use syn::{Attribute, Ident};
 
 use crate::{
@@ -44,6 +44,10 @@ pub struct FieldAttributes {
     /// is needed to let the macro know to generate conversion code with support
     /// for tracking across struct boundaries.
     pub nested: Flag,
+
+    /// Provide a hint if a field is wrapped in either `Option` or `Vec` to
+    /// generate correct code in the `From` impl blocks.
+    pub hint: Option<Hint>,
 }
 
 impl FieldAttributes {
@@ -81,3 +85,10 @@ impl FieldAttributes {
         Ok(())
     }
 }
+
+/// Supported field hints.
+#[derive(Debug, FromMeta)]
+pub enum Hint {
+    Option,
+    Vec,
+}

crates/stackable-versioned-macros/src/codegen/item/field.rs

@@ -0,0 +1,17 @@
+use stackable_versioned::versioned;
+// ---
+#[versioned(version(name = "v1alpha1"), version(name = "v1alpha2"))]
+// ---
+mod versioned {
+    struct Foo {
+        #[versioned(hint(option))]
+        bar: Option<String>,
+
+        #[versioned(hint(vec))]
+        baz: Vec<usize>,
+
+        quux: bool,
+    }
+}
+// ---
+fn main() {}

crates/stackable-versioned-macros/tests/inputs/pass/conversion_hints.rs

@@ -0,0 +1,28 @@
+use stackable_versioned::versioned;
+// ---
+#[versioned(
+    version(name = "v1alpha1"),
+    version(name = "v1alpha2"),
+    options(k8s(experimental_conversion_tracking))
+)]
+// ---
+mod versioned {
+    struct Foo {
+        #[versioned(nested, hint(option))]
+        bar: Option<Bar>,
+
+        #[versioned(hint(vec))]
+        baz: Vec<usize>,
+
+        quux: bool,
+    }
+
+    struct Bar {
+        bar_bar: String,
+
+        #[versioned(added(since = "v1alpha2"))]
+        baz_baz: u8,
+    }
+}
+// ---
+fn main() {}

crates/stackable-versioned-macros/tests/inputs/pass/conversion_tracking_hints.rs

@@ -19,6 +19,8 @@ mod inputs {
     mod pass {
         // mod added;
         // mod basic;
+        // mod conversion_hints;
+        // mod conversion_tracking_hints;
         // mod conversion_tracking;
         // mod crate_overrides;
         // mod docs;

crates/stackable-versioned-macros/tests/snapshots/stackable_versioned_macros__snapshots__pass@conversion_hints.rs.snap

@@ -4,11 +4,18 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Add new `#[versioned(hint)]` argument to provide type hints for struct fields ([#1089]).
+  - `#[versioned(hint(option))]` for fields wrapped in an `Option`. Generates `.map(Into::into)`.
+  - `#[versioned(hint(vec))]` for fields wrapped in an `Vec`. Generates `.into_iter().map(Into::into).collect()`.
+
 ### Fixed
 
 - Correctly emit enum variant fields in `From` impl blocks ([#1086]).
 
 [#1086]: https://github.com/stackabletech/operator-rs/pull/1086
+[#1089]: https://github.com/stackabletech/operator-rs/pull/1089
 
 ## [0.8.1] - 2025-08-21