Add Python language library with import, return type, and call checks

agent-changelog/python-library-implementation.md

@@ -0,0 +1,89 @@
+# Python Library Implementation
+
+## Overview
+This change adds a Python language library to Hielements, providing selectors and checks for Python code analysis.
+
+## Changes to hielements.hie
+
+### New Element: Python Library
+
+Added a new element under `stdlib` to describe the Python library:
+
+```hielements
+element stdlib:
+    # ... existing elements ...
+
+    ## Python library - Python code analysis
+    element python_library:
+        scope python_module = files.file_selector('crates/hielements-core/src/stdlib/python.rs')
+
+        check rust.struct_exists('PythonLibrary')
+        check rust.implements('PythonLibrary', 'Library')
+        check rust.has_tests(python_module)
+```
+
+## Implementation Details
+
+### File Structure
+- **New file**: `crates/hielements-core/src/stdlib/python.rs`
+- **Modified**: `crates/hielements-core/src/stdlib/mod.rs` - registered Python library
+
+### Selectors Implemented
+1. `module_selector(module_path)` - Select Python module by path (e.g., "orders" or "orders.api")
+2. `function_selector(func_name)` - Select function by name
+3. `class_selector(class_name)` - Select class by name
+
+### Checks Implemented (First Checks - Per Requirements)
+
+#### 1. Import Checks
+- `imports(scope, module_name)` - Check if scope imports a module
+- `no_import(scope, module_name)` - Check that scope does NOT import a module
+
+#### 2. Return Type Checks
+- `returns_type(scope, type_name)` - Check if any function in scope returns a given type
+- `function_returns_type(scope, func_name, type_name)` - Check if a specific function returns a given type
+
+#### 3. Call Checks
+- `calls(scope, target)` - Check if scope calls something (function or module)
+- `calls_function(scope, module_name, func_name)` - Check if scope calls a specific function in a module
+- `calls_scope(source_scope, target_scope)` - Check if source scope calls anything in target scope
+
+### Design Decisions
+1. **Pattern matching approach**: Similar to Rust library, uses regex-based pattern matching for Python constructs
+2. **Excluded directories**: Excludes common Python directories like `__pycache__`, `.venv`, `.pytest_cache`, etc.
+3. **Type annotation support**: Handles both simple and generic type annotations (e.g., `-> User`, `-> List[str]`)
+4. **Async function support**: All checks support both regular and async functions
+
+### Testing
+- All 10 unit tests pass
+- Tests cover all selectors and checks
+- Tests use tempfile for isolated test environments
+
+## Usage Examples
+
+```hielements
+import python
+
+element api_service:
+    scope src<python> = python.module_selector('api.orders')
+    scope utils<python> = python.module_selector('utils')
+
+    # Import checks
+    check python.imports(src, 'typing')
+    check python.no_import(src, 'internal_module')
+
+    # Return type checks
+    check python.returns_type(src, 'Order')
+    check python.function_returns_type(src, 'create_order', 'Order')
+
+    # Call checks
+    check python.calls(src, 'validate')
+    check python.calls_function(src, 'logger', 'info')
+    check python.calls_scope(src, utils)
+```
+
+## Alignment with Hielements Philosophy
+- **Extensible**: Follows the Library trait pattern for consistency
+- **Language-agnostic**: Python library integrates seamlessly with existing libraries (files, rust)
+- **Behavioral checks**: Supports architectural validation through call and import checks
+- **Type-aware**: Validates type annotations in Python code

agent-changelog/python-library-summary.md

@@ -0,0 +1,102 @@
+# Python Library Implementation - Final Summary
+
+## Task Completed
+Implemented a Python language library for Hielements with three categories of checks as requested:
+
+### 1. Import Checks
+- ✅ `python.imports(scope, module_name)` - Verify a scope imports a module
+- ✅ `python.no_import(scope, module_name)` - Verify a scope does NOT import a module
+
+### 2. Return Type Checks  
+- ✅ `python.returns_type(scope, type_name)` - Check if any function returns a type
+- ✅ `python.function_returns_type(scope, func_name, type_name)` - Check if specific function returns a type
+
+### 3. Call Checks
+- ✅ `python.calls(scope, target)` - Check if scope calls a function or uses a module
+- ✅ `python.calls_function(scope, module_name, func_name)` - Check if scope calls specific module function
+- ✅ `python.calls_scope(source_scope, target_scope)` - Check if source calls anything in target scope
+
+## Implementation Quality
+
+### Precision
+- Uses regex with word boundaries (`\b`) to prevent false positives
+- Prevents substring matching (e.g., 'os' doesn't match 'osmesa')
+- Handles both regular and async functions
+- Supports generic type annotations (List[T], Dict[K,V], etc.)
+
+### Testing
+- ✅ 10 unit tests (all passing)
+- ✅ 78 total tests in test suite (all passing)
+- ✅ 103 checks in hielements.hie (all passing)
+- ✅ Verified with real Python code examples
+- ✅ Edge cases tested (substring matching, word boundaries)
+
+### Code Quality
+- Follows existing library patterns (rust.rs, files.rs)
+- Proper error handling with LibraryError
+- Clear documentation with examples
+- Known limitations documented
+
+### Integration
+- ✅ Registered in LibraryRegistry
+- ✅ Documented in hielements.hie
+- ✅ Comprehensive example file (examples/python_example.hie)
+- ✅ Works seamlessly with existing checks
+
+## Files Changed
+1. `crates/hielements-core/src/stdlib/python.rs` - New library (427 lines)
+2. `crates/hielements-core/src/stdlib/mod.rs` - Registered Python library
+3. `hielements.hie` - Added python_library element
+4. `examples/python_example.hie` - Comprehensive usage examples
+5. `agent-changelog/python-library-implementation.md` - Implementation notes
+
+## Validation Results
+
+### Real-world Testing
+Created and tested with actual Python modules:
+- ✅ Import detection (positive and negative)
+- ✅ Return type verification (simple and generic)
+- ✅ Function call tracking (direct, qualified, cross-module)
+- ✅ Proper error messages for failures
+
+### Edge Cases
+- ✅ Substring matching prevented ('os' vs 'osmesa')
+- ✅ Word boundaries enforced
+- ✅ Async function support
+- ✅ Multi-line function signatures
+
+## Known Limitations
+- Text-based analysis (not AST-based)
+- Patterns in comments/strings will match (acceptable for basic checks)
+- For production use, could integrate Python AST parser
+
+## Usage Example
+
+```hielements
+import python
+
+element api_service:
+    scope api = python.module_selector('api.orders')
+    scope utils = python.module_selector('utils')
+
+    # Import checks
+    check python.imports(api, 'typing')
+    check python.no_import(api, 'deprecated')
+
+    # Return type checks
+    check python.returns_type(api, 'Order')
+    check python.function_returns_type(api, 'create_order', 'Order')
+
+    # Call checks
+    check python.calls(api, 'validate')
+    check python.calls_function(api, 'logger', 'info')
+    check python.calls_scope(api, utils)
+```
+
+## Conclusion
+The Python library implementation successfully fulfills the requirements with:
+- All requested checks implemented and tested
+- High precision with regex word boundary matching
+- Comprehensive documentation and examples
+- Full integration with Hielements ecosystem
+- Production-ready quality with known limitations documented

crates/hielements-core/src/stdlib/mod.rs

@@ -2,6 +2,7 @@
 
 pub mod external;
 pub mod files;
+pub mod python;
 pub mod rust;
 pub mod wasm;
 
@@ -176,6 +177,7 @@ impl LibraryRegistry {
         };
         // Register built-in libraries
         registry.register(Box::new(files::FilesLibrary::new()));
+        registry.register(Box::new(python::PythonLibrary::new()));
         registry.register(Box::new(rust::RustLibrary::new()));
         registry
     }