feat(#53a): Add AST foundations for module system with visibility support

Foundation work for nested module support (#53). This commit adds the core
AST structures and visibility parsing needed for Rust-style module system.

**Added:**
- `Module`, `UseStatement`, `ModulePath`, `PathSegment` structs to AST
- `Visibility` enum (Public/Private) for type definitions
- Helper methods for `ModulePath` (is_absolute, final_ident, to_string)
- `parse_visibility()` in parser to extract pub keyword from syn

**Changed:**
- `StructDef`, `EnumDef`, `TypeAlias` now include `visibility` field
- `Item` enum extended with `Module` and `Use` variants
- Parser updated to extract visibility from all type definitions
- Transform skips Module/Use items (to be implemented in #53b)
- FileResolver handles Module/Use items in validate_imports

**Testing:**
- All 120 tests passing (107 core + 13 LSP)
- Updated existing test fixtures with visibility field
- No breaking changes to existing functionality

**Next Steps:**
- #53b: Implement module resolution and hierarchical loading
- #53c: Update generators for pub mod output
- #53d: Add tests and examples

Co-Authored-By: Claude <noreply@anthropic.com>

Author: rz1989s

packages/core/src/ast.rs

@@ -19,7 +19,7 @@ pub struct LumosFile {
     pub items: Vec<Item>,
 }
 
-/// An import statement
+/// An import statement (JavaScript-style, legacy)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Import {
     /// Items being imported (e.g., ["UserId", "Timestamp"])
@@ -33,12 +33,77 @@ pub struct Import {
     pub span: Option<proc_macro2::Span>,
 }
 
+/// A module declaration (Rust-style: `mod name;`)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Module {
+    /// Module name (e.g., "models")
+    pub name: String,
+
+    /// Visibility (pub or private)
+    pub visibility: Visibility,
+
+    /// Span information for error reporting
+    #[serde(skip)]
+    pub span: Option<proc_macro2::Span>,
+}
+
+/// A use statement (Rust-style: `use path::Type;`)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct UseStatement {
+    /// Module path (e.g., crate::models::User)
+    pub path: ModulePath,
+
+    /// Optional alias (e.g., `use path::Type as Alias;`)
+    pub alias: Option<String>,
+
+    /// Span information for error reporting
+    #[serde(skip)]
+    pub span: Option<proc_macro2::Span>,
+}
+
+/// Module path (e.g., crate::models::User)
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ModulePath {
+    /// Path segments (e.g., [Crate, Ident("models"), Ident("User")])
+    pub segments: Vec<PathSegment>,
+}
+
+/// A segment in a module path
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub enum PathSegment {
+    /// `crate` keyword
+    Crate,
+
+    /// `super` keyword
+    Super,
+
+    /// `self` keyword
+    SelfPath,
+
+    /// Identifier (module or type name)
+    Ident(String),
+}
+
+/// Visibility modifier
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub enum Visibility {
+    /// Private (no `pub` keyword)
+    #[default]
+    Private,
+
+    /// Public (`pub` keyword)
+    Public,
+}
+
 /// A type alias definition
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TypeAlias {
     /// Alias name (e.g., "UserId")
     pub name: String,
 
+    /// Visibility (pub or private)
+    pub visibility: Visibility,
+
     /// Target type (e.g., PublicKey)
     pub target: TypeSpec,
 
@@ -47,7 +112,7 @@ pub struct TypeAlias {
     pub span: Option<proc_macro2::Span>,
 }
 
-/// An item in a LUMOS file (struct, enum, or type alias)
+/// An item in a LUMOS file (struct, enum, type alias, module, or use statement)
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum Item {
     /// Struct definition
@@ -58,6 +123,12 @@ pub enum Item {
 
     /// Type alias definition
     TypeAlias(TypeAlias),
+
+    /// Module declaration (Rust-style)
+    Module(Module),
+
+    /// Use statement (Rust-style)
+    Use(UseStatement),
 }
 
 /// A struct definition
@@ -66,6 +137,9 @@ pub struct StructDef {
     /// Struct name (e.g., "UserAccount")
     pub name: String,
 
+    /// Visibility (pub or private)
+    pub visibility: Visibility,
+
     /// Attributes applied to the struct (e.g., @solana, @account)
     pub attributes: Vec<Attribute>,
 
@@ -86,6 +160,9 @@ pub struct EnumDef {
     /// Enum name (e.g., "GameState")
     pub name: String,
 
+    /// Visibility (pub or private)
+    pub visibility: Visibility,
+
     /// Attributes applied to the enum (e.g., @solana)
     pub attributes: Vec<Attribute>,
 
@@ -323,6 +400,88 @@ impl Import {
     }
 }
 
+impl ModulePath {
+    /// Create a new module path from segments
+    pub fn new(segments: Vec<PathSegment>) -> Self {
+        Self { segments }
+    }
+
+    /// Create a simple identifier path (e.g., "models" -> [Ident("models")])
+    pub fn from_ident(name: String) -> Self {
+        Self {
+            segments: vec![PathSegment::Ident(name)],
+        }
+    }
+
+    /// Check if this path starts with `crate::`
+    pub fn is_absolute(&self) -> bool {
+        matches!(self.segments.first(), Some(PathSegment::Crate))
+    }
+
+    /// Check if this path starts with `super::`
+    pub fn starts_with_super(&self) -> bool {
+        matches!(self.segments.first(), Some(PathSegment::Super))
+    }
+
+    /// Check if this path starts with `self::`
+    pub fn starts_with_self(&self) -> bool {
+        matches!(self.segments.first(), Some(PathSegment::SelfPath))
+    }
+
+    /// Get the final identifier in the path (e.g., "User" from "crate::models::User")
+    pub fn final_ident(&self) -> Option<&str> {
+        self.segments.iter().rev().find_map(|seg| {
+            if let PathSegment::Ident(name) = seg {
+                Some(name.as_str())
+            } else {
+                None
+            }
+        })
+    }
+
+    /// Convert to string representation (e.g., "crate::models::User")
+    pub fn to_string(&self) -> String {
+        self.segments
+            .iter()
+            .map(|seg| match seg {
+                PathSegment::Crate => "crate".to_string(),
+                PathSegment::Super => "super".to_string(),
+                PathSegment::SelfPath => "self".to_string(),
+                PathSegment::Ident(name) => name.clone(),
+            })
+            .collect::<Vec<_>>()
+            .join("::")
+    }
+}
+
+impl PathSegment {
+    /// Check if this segment is an identifier
+    pub fn is_ident(&self) -> bool {
+        matches!(self, PathSegment::Ident(_))
+    }
+
+    /// Get the identifier name if this is an Ident segment
+    pub fn as_ident(&self) -> Option<&str> {
+        if let PathSegment::Ident(name) = self {
+            Some(name)
+        } else {
+            None
+        }
+    }
+}
+
+impl Visibility {
+    /// Check if this is public visibility
+    pub fn is_public(&self) -> bool {
+        matches!(self, Visibility::Public)
+    }
+
+    /// Check if this is private visibility
+    pub fn is_private(&self) -> bool {
+        matches!(self, Visibility::Private)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -331,6 +490,7 @@ mod tests {
     fn test_struct_has_attribute() {
         let struct_def = StructDef {
             name: "User".to_string(),
+            visibility: Visibility::Private,
             attributes: vec![
                 Attribute {
                     name: "solana".to_string(),
@@ -383,6 +543,7 @@ mod tests {
     fn test_enum_has_attribute() {
         let enum_def = EnumDef {
             name: "GameState".to_string(),
+            visibility: Visibility::Private,
             attributes: vec![Attribute {
                 name: "solana".to_string(),
                 value: None,
@@ -401,6 +562,7 @@ mod tests {
     fn test_enum_is_unit_only() {
         let unit_enum = EnumDef {
             name: "GameState".to_string(),
+            visibility: Visibility::Private,
             attributes: vec![],
             variants: vec![
                 EnumVariant::Unit {
@@ -420,6 +582,7 @@ mod tests {
 
         let mixed_enum = EnumDef {
             name: "GameEvent".to_string(),
+            visibility: Visibility::Private,
             attributes: vec![],
             variants: vec![
                 EnumVariant::Unit {
@@ -466,6 +629,7 @@ mod tests {
     fn test_item_enum() {
         let enum_def = EnumDef {
             name: "Status".to_string(),
+            visibility: Visibility::Private,
             attributes: vec![],
             variants: vec![],
             span: None,

packages/core/src/file_resolver.rs

@@ -177,12 +177,17 @@ impl FileResolver {
         let mut defined_types = HashSet::new();
         for lumos_file in self.loaded_files.values() {
             for item in &lumos_file.items {
-                let name = match item {
-                    crate::ast::Item::Struct(s) => &s.name,
-                    crate::ast::Item::Enum(e) => &e.name,
-                    crate::ast::Item::TypeAlias(a) => &a.name,
+                let name_opt = match item {
+                    crate::ast::Item::Struct(s) => Some(&s.name),
+                    crate::ast::Item::Enum(e) => Some(&e.name),
+                    crate::ast::Item::TypeAlias(a) => Some(&a.name),
+                    crate::ast::Item::Module(m) => Some(&m.name),
+                    // Use statements don't define types, skip them
+                    crate::ast::Item::Use(_) => None,
                 };
-                defined_types.insert(name.clone());
+                if let Some(name) = name_opt {
+                    defined_types.insert(name.clone());
+                }
             }
         }
 

packages/core/src/parser.rs

@@ -35,7 +35,7 @@
 
 use crate::ast::{
     Attribute, AttributeValue, EnumDef, EnumVariant, FieldDef, Import, Item as AstItem,
-    LumosFile, StructDef, TypeAlias, TypeSpec,
+    LumosFile, StructDef, TypeAlias, TypeSpec, Visibility,
 };
 use crate::error::{LumosError, Result};
 use regex::Regex;
@@ -116,6 +116,25 @@ fn extract_imports(input: &str) -> Result<(Vec<Import>, String)> {
     Ok((imports, remaining))
 }
 
+/// Parse visibility from syn::Visibility
+///
+/// Converts `pub` keyword to Visibility::Public, absence to Visibility::Private
+///
+/// # Arguments
+///
+/// * `vis` - syn Visibility node
+///
+/// # Returns
+///
+/// * `Visibility::Public` if `pub` keyword present
+/// * `Visibility::Private` otherwise
+fn parse_visibility(vis: &syn::Visibility) -> Visibility {
+    match vis {
+        syn::Visibility::Public(_) => Visibility::Public,
+        _ => Visibility::Private,
+    }
+}
+
 /// Parse a type alias definition
 ///
 /// Converts `type UserId = PublicKey;` into a TypeAlias AST node.
@@ -131,12 +150,14 @@ fn extract_imports(input: &str) -> Result<(Vec<Import>, String)> {
 fn parse_type_alias(item: syn::ItemType) -> Result<TypeAlias> {
     let name = item.ident.to_string();
     let span = Some(item.ident.span());
+    let visibility = parse_visibility(&item.vis);
 
     // Parse the target type
     let (target, _optional) = parse_type(&item.ty)?;
 
     Ok(TypeAlias {
         name,
+        visibility,
         target,
         span,
     })
@@ -242,6 +263,7 @@ pub fn parse_lumos_file(input: &str) -> Result<LumosFile> {
 fn parse_struct(item: syn::ItemStruct) -> Result<StructDef> {
     let name = item.ident.to_string();
     let span = Some(item.ident.span());
+    let visibility = parse_visibility(&item.vis);
 
     // Extract attributes
     let attributes = parse_attributes(&item.attrs)?;
@@ -269,6 +291,7 @@ fn parse_struct(item: syn::ItemStruct) -> Result<StructDef> {
 
     Ok(StructDef {
         name,
+        visibility,
         attributes,
         fields,
         version,
@@ -280,6 +303,7 @@ fn parse_struct(item: syn::ItemStruct) -> Result<StructDef> {
 fn parse_enum(item: syn::ItemEnum) -> Result<EnumDef> {
     let name = item.ident.to_string();
     let span = Some(item.ident.span());
+    let visibility = parse_visibility(&item.vis);
 
     // Extract attributes
     let attributes = parse_attributes(&item.attrs)?;
@@ -303,6 +327,7 @@ fn parse_enum(item: syn::ItemEnum) -> Result<EnumDef> {
 
     Ok(EnumDef {
         name,
+        visibility,
         attributes,
         variants,
         version,

packages/core/src/transform.rs

@@ -294,6 +294,11 @@ pub fn transform_to_ir(file: LumosFile) -> Result<Vec<TypeDefinition>> {
                 let type_def = transform_type_alias(alias_def, &alias_resolver)?;
                 type_defs.push(TypeDefinition::TypeAlias(type_def));
             }
+            // Module and Use statements are not yet transformed in this pass
+            // They will be handled by ModuleResolver in #53b
+            AstItem::Module(_) | AstItem::Use(_) => {
+                // Skip for now - module resolution is not yet implemented
+            }
         }
     }
 
@@ -373,6 +378,11 @@ fn transform_to_ir_with_resolver_impl(
                 let type_def = transform_type_alias(alias_def, resolver)?;
                 type_defs.push(TypeDefinition::TypeAlias(type_def));
             }
+            // Module and Use statements are not yet transformed
+            // They will be handled by ModuleResolver in #53b
+            AstItem::Module(_) | AstItem::Use(_) => {
+                // Skip for now - module resolution is not yet implemented
+            }
         }
     }