refactor: Modularize token generation

This separates token generation code to be more
modular. Depending on the context, individual
parts of the code need to be placed in different
locations.

Two major refactors are the change of macro input
as well as moving module generation out of the
struct definition generation.

This commit doesn't include changes for enum
generation. This will be done in a separate commit.

Author: Techassi

crates/stackable-versioned-macros/fixtures/snapshots/stackable_versioned_macros__test__k8s_snapshots.snap

@@ -1,33 +1,57 @@
+//! This module contains attributes which can be used on containers (structs and enums).
+//!
+//! Generally there are two different containers, called "standalone" and "nested" based on which
+//! context they are used in. Standalone containers define versioning directly on the struct or
+//! enum. This is useful for single versioned containers. This type of versioning is fine as long
+//! as there is no other versioned container in the same file using the same versions. If that is
+//! the case, the generated modules will collide. There are two possible solutions for this: move
+//! each versioned container into its own file or use the nested declarations. It should be noted
+//! that there might be cases where it is fine to separate each container into its own file. One
+//! such case is when each container serves distinctively different use-cases and provide numerous
+//! associated items like functions.
+//!
+//! In cases where separate files are not desired, the nested mode can be used. The nested mode
+//! allows to declare versions on a module which contains containers which shall be versioned
+//! according to the defined versions. This approach allows defining multiple versioned containers
+//! in the same file without module collisions.
+//!
+//! The attributes used must be tailored to both of these two modes, because not all arguments are
+//! valid in all modes. As such different attributes allow different validation mechanisms. One
+//! such an example is that nested containers must not define versions as the definition is done
+//! on the module. This is in direct contrast to containers used in standalone mode.
+
 use std::{cmp::Ordering, ops::Deref};
 
 use darling::{
     util::{Flag, SpannedValue},
-    Error, FromMeta, Result,
+    Error, FromAttributes, FromMeta, Result,
 };
 use itertools::Itertools;
-use k8s_version::Version;
 
-/// This struct contains supported container attributes.
+use crate::attrs::common::{KubernetesArguments, SkipArguments, VersionArguments};
+
+/// This struct contains supported container attributes which can be applied to structs and enums.
 ///
 /// Currently supported attributes are:
 ///
 /// - `version`, which can occur one or more times. See [`VersionAttributes`].
+/// - `k8s`, which enables Kubernetes specific features and allows customization if these features.
 /// - `options`, which allow further customization of the generated code.
-///    See [`ContainerAttributes`].
+///    See [`StandaloneOptionArguments`].
 #[derive(Debug, FromMeta)]
-#[darling(and_then = ContainerAttributes::validate)]
-pub(crate) struct ContainerAttributes {
+#[darling(and_then = StandaloneContainerAttributes::validate)]
+pub(crate) struct StandaloneContainerAttributes {
     #[darling(multiple, rename = "version")]
-    pub(crate) versions: SpannedValue<Vec<VersionAttributes>>,
+    pub(crate) versions: SpannedValue<Vec<VersionArguments>>,
 
     #[darling(rename = "k8s")]
-    pub(crate) kubernetes_attrs: Option<KubernetesAttributes>,
+    pub(crate) kubernetes_args: Option<KubernetesArguments>,
 
     #[darling(default, rename = "options")]
-    pub(crate) common_option_attrs: OptionAttributes,
+    pub(crate) common_option_args: StandaloneOptionArguments,
 }
 
-impl ContainerAttributes {
+impl StandaloneContainerAttributes {
     fn validate(mut self) -> Result<Self> {
         // Most of the validation for individual version strings is done by the
         // k8s-version crate. That's why the code below only checks that at
@@ -47,7 +71,7 @@ impl ContainerAttributes {
 
         // Ensure that versions are defined in sorted (ascending) order to keep
         // code consistent.
-        if !self.common_option_attrs.allow_unsorted.is_present() {
+        if !self.common_option_args.allow_unsorted.is_present() {
             let original = self.versions.deref().clone();
             self.versions
                 .sort_by(|lhs, rhs| lhs.name.partial_cmp(&rhs.name).unwrap_or(Ordering::Equal));
@@ -91,7 +115,7 @@ impl ContainerAttributes {
 
         // Ensure that the 'k8s' feature is enabled when the 'k8s()'
         // attribute is used.
-        if self.kubernetes_attrs.is_some() && cfg!(not(feature = "k8s")) {
+        if self.kubernetes_args.is_some() && cfg!(not(feature = "k8s")) {
             return Err(Error::custom(
                 "the `#[versioned(k8s())]` attribute can only be used when the `k8s` feature is enabled",
             ));
@@ -101,74 +125,30 @@ impl ContainerAttributes {
     }
 }
 
-/// This struct contains supported version options.
-///
-/// Supported options are:
-///
-/// - `name` of the version, like `v1alpha1`.
-/// - `deprecated` flag to mark that version as deprecated.
-/// - `skip` option to skip generating various pieces of code.
-/// - `doc` option to add version-specific documentation.
-#[derive(Clone, Debug, FromMeta)]
-pub(crate) struct VersionAttributes {
-    pub(crate) deprecated: Flag,
-    pub(crate) name: Version,
-    pub(crate) skip: Option<CommonSkipAttributes>,
-    pub(crate) doc: Option<String>,
-}
-
-/// This struct contains supported option attributes.
+/// This struct contains supported option arguments for containers used in standalone mode.
 ///
-/// Supported attributes are:
+/// Supported arguments are:
 ///
-/// - `allow_unsorted`, which allows declaring versions in unsorted order,
-///   instead of enforcing ascending order.
+/// - `allow_unsorted`, which allows declaring versions in unsorted order, instead of enforcing
+///    ascending order.
 /// - `skip` option to skip generating various pieces of code.
 #[derive(Clone, Debug, Default, FromMeta)]
-pub(crate) struct OptionAttributes {
+pub(crate) struct StandaloneOptionArguments {
     pub(crate) allow_unsorted: Flag,
-    pub(crate) skip: Option<CommonSkipAttributes>,
+    pub(crate) skip: Option<SkipArguments>,
 }
 
-/// This struct contains supported Kubernetes attributes.
-///
-/// Supported attributes are:
-///
-/// - `skip`, which controls skipping parts of the generation.
-/// - `kind`, which allows overwriting the kind field of the CRD. This defaults
-///    to the struct name (without the 'Spec' suffix).
-/// - `group`, which sets the CRD group, usually the domain of the company.
-#[derive(Clone, Debug, FromMeta)]
-pub(crate) struct KubernetesAttributes {
-    pub(crate) skip: Option<KubernetesSkipAttributes>,
-    pub(crate) singular: Option<String>,
-    pub(crate) plural: Option<String>,
-    pub(crate) kind: Option<String>,
-    pub(crate) namespaced: Flag,
-    pub(crate) group: String,
-}
+#[derive(Debug, FromAttributes)]
+#[darling(attributes(versioned))]
+pub(crate) struct NestedContainerAttributes {
+    #[darling(rename = "k8s")]
+    pub(crate) kubernetes_args: Option<KubernetesArguments>,
 
-/// This struct contains supported kubernetes skip attributes.
-///
-/// Supported attributes are:
-///
-/// - `merged_crd` flag, which skips generating the `crd()` and `merged_crd()`
-///   functions are generated.
-#[derive(Clone, Debug, FromMeta)]
-pub(crate) struct KubernetesSkipAttributes {
-    /// Whether the `crd()` and `merged_crd()` generation should be skipped for
-    /// this container.
-    pub(crate) merged_crd: Flag,
+    #[darling(default, rename = "options")]
+    pub(crate) common_option_args: NestedOptionArguments,
 }
 
-/// This struct contains supported common skip attributes.
-///
-/// Supported attributes are:
-///
-/// - `from` flag, which skips generating [`From`] implementations when provided.
 #[derive(Clone, Debug, Default, FromMeta)]
-pub(crate) struct CommonSkipAttributes {
-    /// Whether the [`From`] implementation generation should be skipped for all
-    /// versions of this container.
-    pub(crate) from: Flag,
+pub(crate) struct NestedOptionArguments {
+    pub(crate) skip: Option<SkipArguments>,
 }

crates/stackable-versioned-macros/src/attrs/common/container.rs

@@ -4,7 +4,7 @@ use proc_macro2::Span;
 use syn::{spanned::Spanned, Attribute, Ident, Path, Type};
 
 use crate::{
-    attrs::common::ContainerAttributes,
+    attrs::common::StandaloneContainerAttributes,
     codegen::common::Attributes,
     consts::{DEPRECATED_FIELD_PREFIX, DEPRECATED_VARIANT_PREFIX},
 };
@@ -23,7 +23,7 @@ where
     /// declared container versions.
     fn validate_versions(
         &self,
-        container_attrs: &ContainerAttributes,
+        container_attrs: &StandaloneContainerAttributes,
         item: &I,
     ) -> Result<(), darling::Error>;
 }
@@ -35,7 +35,7 @@ where
 {
     fn validate_versions(
         &self,
-        container_attrs: &ContainerAttributes,
+        container_attrs: &StandaloneContainerAttributes,
         item: &I,
     ) -> Result<(), darling::Error> {
         // NOTE (@Techassi): Can we maybe optimize this a little?
@@ -360,7 +360,6 @@ fn default_default_fn() -> SpannedValue<Path> {
 pub(crate) struct ChangedAttributes {
     pub(crate) since: SpannedValue<Version>,
     pub(crate) from_name: Option<SpannedValue<String>>,
-
     pub(crate) from_type: Option<SpannedValue<Type>>,
 }
 

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

@@ -0,0 +1,32 @@
+use darling::{util::Flag, FromMeta};
+
+/// This struct contains supported Kubernetes arguments.
+///
+/// Supported arguments are:
+///
+/// - `skip`, which controls skipping parts of the generation.
+/// - `kind`, which allows overwriting the kind field of the CRD. This defaults to the struct name
+///    (without the 'Spec' suffix).
+/// - `group`, which sets the CRD group, usually the domain of the company.
+#[derive(Clone, Debug, FromMeta)]
+pub(crate) struct KubernetesArguments {
+    pub(crate) skip: Option<KubernetesSkipArguments>,
+    pub(crate) singular: Option<String>,
+    pub(crate) plural: Option<String>,
+    pub(crate) kind: Option<String>,
+    pub(crate) namespaced: Flag,
+    pub(crate) group: String,
+}
+
+/// This struct contains supported kubernetes skip arguments.
+///
+/// Supported arguments are:
+///
+/// - `merged_crd` flag, which skips generating the `crd()` and `merged_crd()` functions are
+///    generated.
+#[derive(Clone, Debug, FromMeta)]
+pub(crate) struct KubernetesSkipArguments {
+    /// Whether the `crd()` and `merged_crd()` generation should be skipped for
+    /// this container.
+    pub(crate) merged_crd: Flag,
+}

crates/stackable-versioned-macros/src/attrs/common/k8s.rs

@@ -1,5 +1,40 @@
+use darling::{util::Flag, FromMeta};
+use k8s_version::Version;
+
 mod container;
 mod item;
+mod k8s;
+mod module;
 
 pub(crate) use container::*;
 pub(crate) use item::*;
+pub(crate) use k8s::*;
+pub(crate) use module::*;
+
+/// This struct contains supported version arguments.
+///
+/// Supported arguments are:
+///
+/// - `name` of the version, like `v1alpha1`.
+/// - `deprecated` flag to mark that version as deprecated.
+/// - `skip` option to skip generating various pieces of code.
+/// - `doc` option to add version-specific documentation.
+#[derive(Clone, Debug, FromMeta)]
+pub(crate) struct VersionArguments {
+    pub(crate) deprecated: Flag,
+    pub(crate) name: Version,
+    pub(crate) skip: Option<SkipArguments>,
+    pub(crate) doc: Option<String>,
+}
+
+/// This struct contains supported common skip arguments.
+///
+/// Supported arguments are:
+///
+/// - `from` flag, which skips generating [`From`] implementations when provided.
+#[derive(Clone, Debug, Default, FromMeta)]
+pub(crate) struct SkipArguments {
+    /// Whether the [`From`] implementation generation should be skipped for all versions of this
+    /// container.
+    pub(crate) from: Flag,
+}

crates/stackable-versioned-macros/src/attrs/common/mod.rs

@@ -0,0 +1,30 @@
+use darling::{
+    util::{Flag, SpannedValue},
+    FromMeta, Result,
+};
+
+use crate::attrs::common::{SkipArguments, VersionArguments};
+
+#[derive(Debug, FromMeta)]
+#[darling(and_then = ModuleAttributes::validate)]
+pub(crate) struct ModuleAttributes {
+    #[darling(multiple, rename = "version")]
+    pub(crate) versions: SpannedValue<Vec<VersionArguments>>,
+
+    #[darling(default, rename = "options")]
+    pub(crate) common_option_args: ModuleOptionArguments,
+}
+
+impl ModuleAttributes {
+    fn validate(self) -> Result<Self> {
+        // TODO (@Techassi): Make this actually validate
+        Ok(self)
+    }
+}
+
+#[derive(Debug, Default, FromMeta)]
+pub(crate) struct ModuleOptionArguments {
+    pub(crate) skip: Option<SkipArguments>,
+    pub(crate) preserve_module: Flag,
+    pub(crate) allow_unsorted: Flag,
+}