feat: doc reuse

Cargo.toml

@@ -1,3 +1,9 @@
+[workspace]
+
+members = [
+    "macros"
+]
+
 [package]
 name = "streamstore"
 version = "0.1.0"
@@ -14,6 +20,7 @@ secrecy = "0.8.0"
 thiserror = "1.0.63"
 tonic = { version = "0.12.3", features = ["tls", "tls-webpki-roots"] }
 serde = { version = "1.0.210", optional = true, features = ["derive"] }
+macros = { path = "macros" }
 
 [build-dependencies]
 tonic-build = { version = "0.12.2", features = ["prost"] }

build.rs

@@ -3,5 +3,6 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         .bytes(["."])
         .compile_protos(&["proto/s2/v1alpha/s2.proto"], &["proto"])?;
 
+    println!("cargo:rustc-env=COMPILED_PROST_FILE=s2.v1alpha.rs");
     Ok(())
 }

macros/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "macros"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+proc-macro = true
+
+[dependencies]
+proc-macro2 = "1.0.87"
+quote = "1.0.37"
+syn = { version = "2.0.79", features = ["parsing"] }

macros/src/lib.rs

@@ -0,0 +1,321 @@
+use std::{collections::HashMap, fs, path::Path};
+
+use proc_macro::TokenStream;
+use quote::quote;
+use syn::{
+    parse::{Parse, ParseStream, Result},
+    parse_macro_input,
+    punctuated::Punctuated,
+    token::Comma,
+    DeriveInput, Expr, Field, Fields, FieldsNamed, File, Ident, Item, ItemEnum, ItemStruct, Lit,
+    LitStr, Token, Variant,
+};
+
+type CollectedDocs = (Vec<String>, HashMap<String, Vec<String>>);
+
+fn find_type_docs(parsed_file: File, target_name: &str) -> Option<CollectedDocs> {
+    for item in parsed_file.items {
+        if let Some(docs) = match item {
+            Item::Mod(m) => match m.content {
+                Some((_, items)) => find_mod_docs(items, target_name),
+                None => None,
+            },
+            Item::Struct(s) => find_struct_docs(s, target_name.to_string()),
+            Item::Enum(e) => find_enum_docs(e, target_name.to_string()),
+            _ => None,
+        } {
+            return Some(docs);
+        }
+    }
+
+    None
+}
+
+fn find_enum_docs(ast_enum: ItemEnum, target_enum_name: String) -> Option<CollectedDocs> {
+    if ast_enum.ident == target_enum_name {
+        let enum_docs = extract_doc_strings(&ast_enum.attrs);
+        let mut variant_docs = HashMap::new();
+
+        for variant in ast_enum.variants {
+            variant_docs.insert(
+                variant.ident.to_string(),
+                extract_doc_strings(&variant.attrs),
+            );
+
+            for field in variant.fields {
+                if let Some(field_name) = field.ident.map(|i| i.to_string()) {
+                    variant_docs.insert(field_name, extract_doc_strings(&field.attrs));
+                }
+            }
+        }
+
+        return Some((enum_docs, variant_docs));
+    }
+
+    None
+}
+
+fn find_struct_docs(ast_struct: ItemStruct, target_struct_name: String) -> Option<CollectedDocs> {
+    if ast_struct.ident == target_struct_name {
+        let struct_docs = extract_doc_strings(&ast_struct.attrs);
+
+        let field_docs = ast_struct
+            .fields
+            .iter()
+            .filter_map(|field| {
+                Some((
+                    field.ident.as_ref()?.to_string(),
+                    extract_doc_strings(&field.attrs),
+                ))
+            })
+            .collect();
+
+        return Some((struct_docs, field_docs));
+    }
+
+    None
+}
+
+/// Recursively search for the target module or type in the given items.
+fn find_mod_docs(items: Vec<Item>, target_name: &str) -> Option<CollectedDocs> {
+    for item in items {
+        if let Item::Struct(s) = item.clone() {
+            if s.ident == target_name {
+                let docs_iter = extract_doc_strings(&s.attrs);
+
+                let field_docs = s
+                    .fields
+                    .iter()
+                    .filter_map(|field| {
+                        Some((
+                            field.ident.as_ref()?.to_string(),
+                            extract_doc_strings(&field.attrs),
+                        ))
+                    })
+                    .collect();
+
+                return Some((docs_iter, field_docs));
+            }
+        }
+
+        if let Item::Enum(e) = item.clone() {
+            if e.ident == target_name {
+                let docs_iter = extract_doc_strings(&e.attrs);
+                let mut docs = HashMap::new();
+
+                for variant in e.variants {
+                    docs.insert(
+                        variant.ident.to_string(),
+                        extract_doc_strings(&variant.attrs),
+                    );
+
+                    for field in variant.fields {
+                        if let Some(field_name) = field.ident.map(|i| i.to_string()) {
+                            docs.insert(field_name, extract_doc_strings(&field.attrs));
+                        }
+                    }
+                }
+                return Some((docs_iter, docs));
+            }
+        }
+
+        if let Item::Mod(m) = item {
+            if let Some((_, items)) = m.content {
+                return find_mod_docs(items, target_name);
+            }
+        }
+    }
+
+    None
+}
+
+fn extract_doc_strings(attrs: &[syn::Attribute]) -> Vec<String> {
+    attrs
+        .iter()
+        .filter_map(|attr| {
+            if attr.path().is_ident("doc") {
+                if let syn::Meta::NameValue(name_value) = &attr.meta {
+                    match &name_value.value {
+                        Expr::Lit(doc_expr) => match &doc_expr.lit {
+                            Lit::Str(doc_lit) => Some(doc_lit.value()),
+                            _ => None,
+                        },
+                        _ => None,
+                    }
+                } else {
+                    None
+                }
+            } else {
+                None
+            }
+        })
+        .collect()
+}
+
+#[derive(Debug)]
+struct KeyValue {
+    key: Ident,
+    _eq: Token![=],
+    value: LitStr,
+}
+
+impl Parse for KeyValue {
+    fn parse(input: ParseStream) -> Result<Self> {
+        Ok(KeyValue {
+            key: input.parse()?,
+            _eq: input.parse()?,
+            value: input.parse()?,
+        })
+    }
+}
+
+#[derive(Debug)]
+struct RenameArgs {
+    mapping: HashMap<String, String>,
+}
+
+impl Parse for RenameArgs {
+    fn parse(input: ParseStream) -> Result<Self> {
+        let mut mapping = HashMap::new();
+
+        while !input.is_empty() {
+            let pair = input.parse::<KeyValue>()?;
+            mapping.insert(pair.key.to_string(), pair.value.value());
+            if !input.is_empty() {
+                input.parse::<Token![,]>()?;
+            }
+        }
+
+        Ok(RenameArgs { mapping })
+    }
+}
+
+#[proc_macro_attribute]
+pub fn sync_docs(args: TokenStream, input: TokenStream) -> TokenStream {
+    let args = parse_macro_input!(args as RenameArgs);
+    let mut input_ast = parse_macro_input!(input as DeriveInput);
+
+    let type_name = input_ast.ident.to_string();
+    let type_name = args.mapping.get(&type_name).unwrap_or(&type_name);
+
+    let source_path = {
+        let out_dir = match std::env::var("OUT_DIR") {
+            Ok(dir) => dir,
+            Err(_) => {
+                return syn::Error::new(proc_macro2::Span::call_site(), "OUT_DIR is required")
+                    .to_compile_error()
+                    .into();
+            }
+        };
+
+        let prost_file = match std::env::var("COMPILED_PROST_FILE") {
+            Ok(file) => file,
+            Err(_) => {
+                return syn::Error::new(
+                    proc_macro2::Span::call_site(),
+                    "COMPILED_PROST_FILE is required",
+                )
+                .to_compile_error()
+                .into();
+            }
+        };
+
+        Path::new(&out_dir).join(prost_file)
+    };
+
+    let raw_file_content = match fs::read_to_string(source_path) {
+        Ok(content) => content,
+        Err(_) => {
+            return syn::Error::new(
+                proc_macro2::Span::call_site(),
+                "Failed to read the compiled prost file",
+            )
+            .to_compile_error()
+            .into();
+        }
+    };
+
+    let parsed_file = match syn::parse_file(&raw_file_content) {
+        Ok(file) => file,
+        Err(_) => {
+            return syn::Error::new(
+                proc_macro2::Span::call_site(),
+                "Failed to parse the compiled prost file",
+            )
+            .to_compile_error()
+            .into();
+        }
+    };
+
+    if let Some((type_docs, field_or_variant_docs)) = find_type_docs(parsed_file, type_name) {
+        for doc in type_docs {
+            input_ast.attrs.push(syn::parse_quote!(#[doc = #doc]));
+        }
+
+        match &mut input_ast.data {
+            syn::Data::Struct(data) => {
+                if let Fields::Named(FieldsNamed { named: fields, .. }) = &mut data.fields {
+                    update_struct_field_docs(fields, &field_or_variant_docs, &args.mapping);
+                }
+            }
+            syn::Data::Enum(data) => {
+                update_enum_variant_docs(&mut data.variants, &field_or_variant_docs, &args.mapping);
+            }
+            _ => {}
+        };
+    }
+
+    let expanded = quote! {
+        #input_ast
+    };
+
+    TokenStream::from(expanded)
+}
+
+fn update_struct_field_docs(
+    fields: &mut Punctuated<Field, Comma>,
+    field_docs: &HashMap<String, Vec<String>>,
+    field_mapping: &HashMap<String, String>,
+) {
+    for field in fields {
+        if let Some(field_name) = field.ident.as_ref().map(|i| i.to_string()) {
+            let field_name = field_mapping.get(&field_name).unwrap_or(&field_name);
+            if let Some(docs) = field_docs.get(field_name) {
+                field
+                    .attrs
+                    .extend(docs.iter().map(|doc| syn::parse_quote!(#[doc = #doc])));
+            }
+        }
+    }
+}
+
+fn update_enum_variant_docs(
+    variants: &mut Punctuated<Variant, Comma>,
+    variant_docs: &HashMap<String, Vec<String>>,
+    variant_mapping: &HashMap<String, String>,
+) {
+    for variant in variants {
+        let variant_name = variant.ident.to_string();
+        let variant_name = variant_mapping.get(&variant_name).unwrap_or(&variant_name);
+        if let Some(variant_docs) = variant_docs.get(variant_name) {
+            variant.attrs.extend(
+                variant_docs
+                    .iter()
+                    .map(|doc| syn::parse_quote!(#[doc = #doc])),
+            );
+        }
+
+        for field in &mut variant.fields {
+            if let Some(field_name) = field.ident.as_ref().map(|i| i.to_string()) {
+                let field_name = variant_mapping.get(&field_name).unwrap_or(&field_name);
+                if let Some(field_docs) = variant_docs.get(field_name) {
+                    field.attrs.extend(
+                        field_docs
+                            .iter()
+                            .map(|doc| syn::parse_quote!(#[doc = #doc])),
+                    );
+                }
+            }
+        }
+    }
+}

src/streams.rs

@@ -80,7 +80,7 @@ pub enum AppendRecordStreamError {
 }
 
 /// Wrapper over a stream of append records that can be sent over to
-/// [`StreamClient::append_session`].
+/// [`crate::client::StreamClient::append_session`].
 pub struct AppendRecordStream<R, S>
 where
     R: Into<types::AppendRecord>,