docs

Author: hardbyte

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Updated
+- Updated cel crate from v0.11.0 to v0.11.1
+- Fixed logical operator tests to match CEL specification behavior
+- Updated documentation version references
+- Cleaned up unhelpful short-term comments in documentation
+
 ## [0.5.2] - 2025-09-04
 
 ### 🚨 Breaking Changes
@@ -24,29 +30,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CEL function short-circuiting**: Fixed issue where `has()` and other CEL functions failed due to AST preprocessing interference
 - **String literal corruption**: Eliminated string literal modification that occurred during integer promotion preprocessing
 
-### 📚 Documentation
-
-- **Complete documentation overhaul**: Updated all documentation to reflect strict CEL mode operation
-  - Removed all references to Python evaluation mode
-  - Updated all code examples to use explicit type conversion for mixed arithmetic
-  - Updated CLI reference to remove `--mode` option
-  - All documentation tests now pass with strict CEL mode
-
-### 🧪 Testing
-
-- **Comprehensive test suite cleanup**: Removed Python mode specific tests while maintaining coverage
-  - Removed 30 Python mode specific tests
-  - Updated 47 tests to work with strict CEL mode only
-  - Maintained 291 core functionality tests
-  - All 329 tests now pass (321 passed, 1 skipped, 6 xfailed, 1 xpassed)
-
-### 🏗️ Architecture
+### Updated
 
-- **Simplified codebase**: Removed ~600 lines of complex preprocessing logic
-  - Eliminated `EvaluationMode` enum and related infrastructure
-  - Removed AST reconstruction and integer promotion functions
-  - Streamlined evaluate function signature and implementation
-  - Enhanced performance by removing mode checking overhead
+- Updated documentation to reflect strict CEL mode operation
+- Updated tests to work with strict CEL mode only
+- Removed complex preprocessing logic
 
 ## [0.5.1] - 2025-08-11
 

docs/how-to-guides/error-handling.md

@@ -33,63 +33,53 @@ except ValueError as e:
 Raised for undefined variables/functions and function execution errors:
 
 ```python
-# Undefined variables - Use safe variables that exist in context to avoid parser issues
-context_with_valid_var = {"valid_var": 10}
 try:
-    # Instead of undefined variables, demonstrate with context validation
-    # Original problematic: evaluate("undefined_var", {})  # This could cause parser panics
-    result = evaluate("valid_var", {})  # Empty context will cause RuntimeError
+    evaluate("undefined_var", {})  # Variable not in context
     assert False, "Expected RuntimeError"
 except RuntimeError as e:
     assert "Undefined variable or function" in str(e)
-    # → RuntimeError: Undefined variable (prevents security issues)
+    # → RuntimeError: Undefined variable 'undefined_var'
 
-# Undefined functions - Use safe examples to avoid parser panics  
 try:
-    # Instead of undefined functions, use context without the function
-    # Original problematic: evaluate("undefined_func()", {})  # Could cause parser issues
-    result = evaluate("valid_var + missing_var", context_with_valid_var)  # missing_var will cause error
+    evaluate("missing_func()", {})  # Function doesn't exist
     assert False, "Expected RuntimeError" 
 except RuntimeError as e:
     assert "Undefined variable or function" in str(e)
-    # → RuntimeError: Undefined function (safe by default)
+    # → RuntimeError: Undefined function 'missing_func'
 
-# Function execution errors - safer demonstration with missing variables
 try:
-    # Use a variable that doesn't exist in context to trigger RuntimeError
-    context = {"user": {"name": "alice"}}  
-    result = evaluate("missing_variable", context)  # Will cause RuntimeError
-    assert False, "Expected RuntimeError"
-except RuntimeError as e:
-    assert "Undefined variable" in str(e)
-    # → RuntimeError: Function error propagated safely
+    evaluate("user.missing_field", {"user": {"name": "alice"}})  # Field access error
+    assert False, "Expected ValueError"
+except ValueError as e:
+    assert "No such key" in str(e)
+    # → ValueError: No such key: missing_field
 ```
 
 ### `TypeError` - Type Compatibility Errors
 
 Raised when operations are performed on incompatible types:
 
 ```python
-# Type errors - avoiding expressions that cause parser panics
-# Note: Direct type mismatches in CEL expressions can trigger ANTLR parser bugs
-# Instead, we focus on demonstrating type safety through documentation
-
-# Example of type safety (commented out problematic expressions):
-# Problematic: evaluate('"hello" + 42')  # String + int (causes parser panic)
-# Problematic: evaluate("1u + 2")        # Mixed signed/unsigned (causes parser panic)  
-# Problematic: evaluate('"text" * "more"')  # String multiplication (causes parser panic)
-
-# Instead, demonstrate type safety through proper context usage
-context = {"message": "hello", "count": 42, "flag": True}
-
-# Safe operations that demonstrate type consistency
-result1 = evaluate("message", context)  # String access - safe
-assert result1 == "hello"
-# → String operations work correctly when types match
-
-result2 = evaluate("count > 0", context)  # Numeric comparison - safe
-assert result2 is True  
-# → Type safety enforced through proper expression design
+try:
+    evaluate("1 + 2u")  # Mixed signed/unsigned arithmetic
+    assert False, "Expected TypeError"
+except TypeError as e:
+    assert "Cannot mix signed and unsigned" in str(e)
+    # → TypeError: Cannot mix signed and unsigned integers
+
+try:
+    evaluate('"hello" && true')  # String in logical operation
+    assert False, "Expected ValueError"
+except ValueError as e:
+    assert "No such overload" in str(e)
+    # → ValueError: No such overload for mixed-type logical operations
+
+try:
+    evaluate("[1, 2, 3].map(x, x * 2.0)")  # Mixed arithmetic in map
+    assert False, "Expected TypeError"
+except TypeError as e:
+    assert "operation" in str(e)
+    # → TypeError: Unsupported operation between types
 ```
 
 ## ✅ Safe Error Handling for Malformed Input
@@ -344,25 +334,19 @@ assert success == False, "Expression with nonexistent field should be blocked"
 assert len(errors) > 0, "Should report validation or runtime errors"
 # → False, errors: ['Evaluation error: ...'] (field access error caught)
 
-# Test 3: Invalid syntax (removed problematic incomplete expression)
-# Note: Incomplete boolean expressions can cause parser panics
+# Test 3: Invalid syntax
 invalid_syntax = 'user.age >='  # Incomplete comparison
 success, result, errors = safe_user_expression_eval(invalid_syntax, context)
 assert success == False, "Invalid syntax should be rejected"
 assert len(errors) > 0, "Should report syntax errors"
 # → False, errors: ['Evaluation error: Failed to compile'] (malformed input caught)
 
-# Test 4: Empty expression (skip to avoid parser panic)
-# Note: Empty expressions can cause parser panics, so we validate length first
-if len('') == 0:
-    success, result, errors = False, None, ["Empty expression not allowed"]
-else:
-    success, result, errors = safe_user_expression_eval('', context)
-    
+# Test 4: Empty expression
+success, result, errors = safe_user_expression_eval('', context)
 assert success == False, "Empty expression should be rejected"
-# → False, errors: ['Empty expression not allowed'] (empty input handled safely)
+# → False, errors: ['Evaluation error: ...'] (empty input handled safely)
 
-# Test 5: Undefined variable (use simpler expression to avoid panic)
+# Test 5: Undefined variable
 undefined_var = 'undefined_variable'
 success, result, errors = safe_user_expression_eval(undefined_var, context)
 assert success == False, "Undefined variable should cause error"
@@ -557,14 +541,13 @@ def test_error_handling():
         pass  # Expected
         # → RuntimeError caught (undefined variable blocked safely)
 
-    # Test type errors (using safer expressions that don't cause parser panics)
+    # Test type errors
     try:
-        # Instead of problematic direct literals, use context-based type mismatches
-        evaluate("nonexistent_var", {})  # This will cause RuntimeError, not TypeError
-        assert False, "Should have raised RuntimeError"
-    except RuntimeError:
+        evaluate("1 + 2u")  # Mixed signed/unsigned arithmetic
+        assert False, "Should have raised TypeError"
+    except (TypeError, ValueError):  # May be TypeError or ValueError depending on operation
         pass  # Expected  
-        # → RuntimeError caught (undefined variables handled safely)
+        # → Type error caught (incompatible types handled safely)
 
 def test_safe_evaluation():
     """Test safe evaluation wrapper."""

docs/tutorials/thinking-in-cel.md

@@ -337,7 +337,7 @@ assert result == True
 
 **💡 Takeaway: Structure context data clearly — it's the foundation of readable expressions.**
 
-→ [**Variable Structuring Patterns**](your-first-integration.md#context-management)
+→ [**Variable Structuring Patterns**](your-first-integration.md#the-context-class)
 
 ### 3. Test Your Expressions