venus_macros/
lib.rs

1//! Procedural macros for Venus reactive notebook environment.
2//!
3//! This crate provides the `#[venus::cell]` attribute macro that marks functions
4//! as notebook cells. The macro is a passthrough in library mode (for `cargo build`),
5//! while the Venus runtime interprets these attributes for reactive execution.
6
7use proc_macro::TokenStream;
8use quote::quote;
9use syn::{ItemFn, parse_macro_input};
10
11/// Marks a function as a notebook cell.
12///
13/// # Cell Semantics
14///
15/// - **Dependencies**: Function parameters define inputs from other cells
16/// - **Output**: Return type defines what this cell provides to dependents
17/// - **Documentation**: `///` comments become cell descriptions in the notebook UI
18///
19/// # Example
20///
21/// ```rust,ignore
22/// use venus::prelude::*;
23///
24/// /// Load data from CSV file
25/// #[venus::cell]
26/// pub fn load_data() -> DataFrame {
27///     CsvReader::from_path("data.csv")
28///         .unwrap()
29///         .finish()
30///         .unwrap()
31/// }
32///
33/// /// Process the loaded data
34/// #[venus::cell]
35/// pub fn process(data: &DataFrame) -> DataFrame {
36///     data.clone()
37///         .lazy()
38///         .filter(col("value").gt(lit(100)))
39///         .collect()
40///         .unwrap()
41/// }
42/// ```
43///
44/// # Behavior
45///
46/// In **library mode** (when compiled with `cargo build`), this attribute is a
47/// passthrough - the function is compiled as-is. This ensures full compatibility
48/// with rust-analyzer, cargo, and clippy.
49///
50/// In **Venus runtime mode**, the attribute signals to the execution engine that
51/// this function should be treated as a reactive cell with automatic dependency
52/// tracking and re-execution.
53#[proc_macro_attribute]
54pub fn cell(attr: TokenStream, item: TokenStream) -> TokenStream {
55    let input = parse_macro_input!(item as ItemFn);
56
57    // Parse optional attributes (future use: priority, cache settings, etc.)
58    let _attr_tokens = proc_macro2::TokenStream::from(attr);
59
60    // For now, passthrough the function unchanged.
61    // The Venus runtime will parse the source file with `syn` to extract
62    // cell metadata (dependencies, return type, doc comments).
63    //
64    // We add a hidden marker attribute that the runtime can detect,
65    // but this doesn't affect compilation.
66    let vis = &input.vis;
67    let sig = &input.sig;
68    let block = &input.block;
69    let attrs = &input.attrs;
70
71    let expanded = quote! {
72        #(#attrs)*
73        #[doc(hidden)]
74        #[allow(dead_code)]
75        const _: () = {
76            // Marker for Venus runtime detection
77            // This const is optimized away but appears in the AST
78        };
79        #vis #sig #block
80    };
81
82    TokenStream::from(expanded)
83}
84
85#[cfg(test)]
86mod tests {
87    #[test]
88    fn test_cell_macro_compiles() {
89        // This test just verifies the macro crate compiles
90        // Actual macro testing requires a separate test crate
91    }
92}
venus_macros/lib.rs

venus_macros/
lib.rs
