fix: Improve module system validation and restrictions

- Enhanced export constant validation to verify items are actually constants
- Improved type checking for include/export statements with proper error messages
- Relaxed control flow restrictions to allow return statements in included files
- Clarified export statement documentation with current benefits and usage

Fixes identified issues from code review while maintaining backward compatibility.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: logbie <logbie@users.noreply.github.com>

Author: claude[bot]

Docs/04-advanced-features/modules.md

@@ -510,9 +510,9 @@ end try
 
 ## Limitations
 
-## Export Statement (V2 Foundation)
+## Export Statement
 
-WFL now includes an `export` statement that validates the existence of items for future module namespaces:
+WFL includes an `export` statement that documents and validates module interfaces:
 
 ```wfl
 # Define items in a module
@@ -527,13 +527,18 @@ end
 
 store constant VERSION as "1.0.0"
 
-# Export specific items for future namespace features
+# Document which items are intended for external use
 export container Person
 export action greet
 export constant VERSION
 ```
 
-The export statement currently validates that the named item exists in the current scope. In future versions, this will enable selective module exposure.
+**Current Benefits:**
+- **Documentation**: Makes module interface explicit and clear
+- **Validation**: Ensures exported items actually exist at compile/lint time
+- **Best Practices**: Encourages conscious design of module interfaces
+
+**Future Enhancements:** The export statement establishes the foundation for selective module exposure and namespace control in future WFL versions.
 
 ### Current Limitations (V2)
 

src/interpreter/mod.rs

@@ -3001,11 +3001,11 @@ impl Interpreter {
                 // 10. Handle result
                 match result {
                     Ok((_, ControlFlow::None)) => Ok((Value::Null, ControlFlow::None)),
-                    Ok((_, ControlFlow::Return(_))) => Err(RuntimeError::new(
-                        "Cannot use 'return' in included file scope".to_string(),
-                        *line,
-                        *column,
-                    )),
+                    Ok((val, ControlFlow::Return(_))) => {
+                        // Return statements in included files are allowed and simply return the value
+                        // This enables utility functions in included files to use return statements
+                        Ok((val, ControlFlow::None))
+                    }
                     Ok((_, ControlFlow::Break)) => Err(RuntimeError::new(
                         "Cannot use 'break' in included file scope".to_string(),
                         *line,
@@ -3097,11 +3097,20 @@ impl Interpreter {
                         }
                     }
                     ExportType::Constant => {
-                        // Check if constant exists
+                        // Check if the variable exists and is actually a constant
                         if let Some(_value) = env.borrow().get(name) {
-                            // For constants, we could validate it's actually a constant
-                            // For now, just verify it exists
-                            Ok((Value::Null, ControlFlow::None))
+                            if env.borrow().is_constant(name) {
+                                Ok((Value::Null, ControlFlow::None))
+                            } else {
+                                Err(RuntimeError::new(
+                                    format!(
+                                        "Variable '{}' is not a constant and cannot be exported as one",
+                                        name
+                                    ),
+                                    *line,
+                                    *column,
+                                ))
+                            }
                         } else {
                             Err(RuntimeError::new(
                                 format!("Constant '{}' not found in current scope", name),

src/typechecker/mod.rs

@@ -1672,15 +1672,106 @@ impl TypeChecker {
                 }
             }
 
-            Statement::IncludeStatement { path, .. } => {
-                // Type check the path expression
-                self.infer_expression_type(path);
-                // Include statements execute in parent scope but don't need special type checking
+            Statement::IncludeStatement {
+                path, line, column, ..
+            } => {
+                // Type check the path expression - must be a string
+                let path_type = self.infer_expression_type(path);
+                if path_type != Type::Text && path_type != Type::Unknown && path_type != Type::Error
+                {
+                    self.type_error(
+                        "Expected string for include path".to_string(),
+                        Some(Type::Text),
+                        Some(path_type),
+                        *line,
+                        *column,
+                    );
+                }
+                // Note: Include statements execute in parent scope, making their symbols available
+                // Full symbol resolution would require parsing the included file during type checking
             }
 
-            Statement::ExportStatement { .. } => {
-                // Export statements are validated at runtime
-                // Type checking here would require deeper integration
+            Statement::ExportStatement {
+                export_type,
+                name,
+                line,
+                column,
+                ..
+            } => {
+                // Basic type checking for export statements
+                // Check if the exported item exists in the current scope
+                match export_type {
+                    crate::parser::ast::ExportType::Container => {
+                        if let Some(_container) = self.analyzer.get_container(name) {
+                            // Container exists - export is valid
+                        } else {
+                            self.type_error(
+                                format!("Container '{}' not found for export", name),
+                                None,
+                                None,
+                                *line,
+                                *column,
+                            );
+                        }
+                    }
+                    crate::parser::ast::ExportType::Action => {
+                        // Check if action exists as a symbol in the current scope
+                        if let Some(symbol) = self.analyzer.get_symbol(name) {
+                            match symbol.kind {
+                                crate::analyzer::SymbolKind::Function { .. } => {
+                                    // Action exists - export is valid
+                                }
+                                _ => {
+                                    self.type_error(
+                                        format!(
+                                            "'{}' is not an action and cannot be exported as one",
+                                            name
+                                        ),
+                                        None,
+                                        None,
+                                        *line,
+                                        *column,
+                                    );
+                                }
+                            }
+                        } else {
+                            self.type_error(
+                                format!("Action '{}' not found for export", name),
+                                None,
+                                None,
+                                *line,
+                                *column,
+                            );
+                        }
+                    }
+                    crate::parser::ast::ExportType::Constant => {
+                        // Check if variable exists as a symbol in the current scope
+                        if let Some(symbol) = self.analyzer.get_symbol(name) {
+                            match symbol.kind {
+                                crate::analyzer::SymbolKind::Variable { .. } => {
+                                    // Variable exists, runtime will verify it's actually a constant
+                                }
+                                _ => {
+                                    self.type_error(
+                                        format!("'{}' is not a variable and cannot be exported as constant", name),
+                                        None,
+                                        None,
+                                        *line,
+                                        *column,
+                                    );
+                                }
+                            }
+                        } else {
+                            self.type_error(
+                                format!("Constant '{}' not found for export", name),
+                                None,
+                                None,
+                                *line,
+                                *column,
+                            );
+                        }
+                    }
+                }
             }
         }
     }

test_export_validation.wfl

@@ -0,0 +1,9 @@
+# Test export constant validation
+
+store new constant VALID_CONSTANT as "This is a constant"
+store invalid_variable as "This is not a constant"
+
+export constant VALID_CONSTANT  # This should work
+
+# This should fail at runtime - trying to export a non-constant as constant
+export constant invalid_variable

test_fix_verification.wfl

@@ -0,0 +1,35 @@
+# Test to verify the fixes for module system issues
+
+# Test 1: Return statement in included files (should now work)
+define action called utility_function with parameters:
+    display "This function uses return"
+    return 42
+end action
+
+# Test 2: Constants for export testing  
+store new constant API_VERSION as "2.0.1"
+
+# Test 3: Variable for export testing
+store api_endpoint as "https://api.example.com"
+
+# Test 4: Container for export testing
+create container TestItem:
+    property name: Text
+end
+
+# Test 5: Export statements
+export action utility_function
+export constant API_VERSION
+export container TestItem
+
+display "Test file loaded successfully with return handling"
+
+# Use a return statement at the top level to test return handling
+check if API_VERSION is equal to "2.0.1":
+    display "Version check passed"
+    return 0
+otherwise:
+    display "Version check failed"
+end check
+
+display "This should not be displayed due to return"

test_main_fix.wfl

@@ -0,0 +1,12 @@
+# Main test file to verify include statements work with return
+
+display "Before include"
+
+include from "test_fix_verification.wfl"
+
+display "After include - this should be displayed despite return in included file"
+
+# Variables from included file should be available at runtime
+# display "API_VERSION from included file: " + API_VERSION
+
+display "All tests passed!"