Wfl containers

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-WFL (WebFirst Language) is a natural language programming language implemented in Rust. It features intuitive syntax like "store x as 5" and "display 'Hello'", with static typing, async support, and comprehensive development tooling.
+WFL (WebFirst Language) is a natural language programming language implemented in Rust. It features intuitive syntax like "store x as 5" and "display 'Hello'", with static typing, async support, and comprehensive development tooling. The project is developed with AI assistance from Devin.ai, ChatGPT, and Claude.
 
 ## Memory Bank Context
 
@@ -31,37 +31,121 @@ This project uses a comprehensive memory bank system located in `.kilocode/rules
 3. Add new tests for new features
 4. Document any edge cases
 
-### Development Commands
+## Core Development Commands
+
+### Building and Testing
 ```bash
-# Build the project
+# Standard build and test cycle
+cargo fmt --all              # Format code
+cargo build                  # Build debug version
+cargo test                   # Run all tests
+cargo clippy --all-targets -- -D warnings  # Lint code
+
+# Release build
 cargo build --release
+cargo test --release
+
+# Run a single test
+cargo test test_name
+
+# Run tests with output
+cargo test -- --nocapture
+```
 
+### Running WFL Programs
+```bash
 # Run a WFL program
-cargo run -- program.wfl
+cargo run -- path/to/program.wfl
 
-# Run with debugging
-cargo run -- program.wfl --debug > debug.txt 2>&1
+# With debug output
+cargo run -- --debug path/to/program.wfl > debug.txt 2>&1
+
+# Interactive mode (REPL)
+cargo run -- --interactive
+```
 
-# Run all tests
-cargo test
+### Code Quality Tools
+```bash
+# Lint WFL code
+cargo run -- --lint script.wfl
+
+# Static analysis
+cargo run -- --analyze script.wfl
+
+# Auto-fix code issues
+cargo run -- --fix script.wfl --in-place
+
+# Check configuration
+cargo run -- --configCheck
+cargo run -- --configFix
+```
+
+### VSCode Extension Development
+```bash
+cd vscode-extension
+npm install
+npm run compile     # Build extension
+npm run watch      # Watch mode
+npm run test       # Run tests
+```
 
-# Lint a program
-cargo run -- --lint program.wfl
+## CLI Flag Reference
 
-# Analyze for issues
-cargo run -- --analyze program.wfl
+| Flag | Description | Example |
+|------|-------------|---------|
+| `--lex` | Output lexer tokens only | `cargo run -- --lex program.wfl` |
+| `--parse` | Output AST only | `cargo run -- --parse program.wfl` |
+| `--lint` | Check code style | `cargo run -- --lint program.wfl` |
+| `--analyze` | Static analysis | `cargo run -- --analyze program.wfl` |
+| `--fix` | Auto-format code | `cargo run -- --fix program.wfl` |
+| `--in-place` | Modify file directly | `cargo run -- --fix program.wfl --in-place` |
+| `--check` | Dry run for --fix | `cargo run -- --fix program.wfl --check` |
+| `--debug` | Enable debug output | `cargo run -- --debug program.wfl` |
+| `--config` | Specify config file | `cargo run -- --config custom.wflcfg program.wfl` |
+| `--time` | Show execution time | `cargo run -- --time program.wfl` |
+| `-v, --version` | Show version info | `cargo run -- --version` |
 
-# Auto-fix formatting
-cargo run -- --fix program.wfl --in-place
+## Architecture Overview
 
-# Start REPL
-cargo run
+### Module Structure
+The codebase follows a pipeline architecture:
 
-# Check code quality
-cargo fmt --all -- --check
-cargo clippy --all-targets --all-features -- -D warnings
+```
+Input (.wfl) → Lexer → Parser → Analyzer → Type Checker → Interpreter → Output
+                ↓       ↓         ↓           ↓              ↓
+              Tokens   AST    Validated   Type Info    Execution
+                              AST                       Results
 ```
 
+1. **Lexer** (`src/lexer/`) - Tokenizes source code using Logos library
+2. **Parser** (`src/parser/`) - Builds AST with natural language support
+3. **Analyzer** (`src/analyzer/`) - Semantic analysis and validation
+4. **Type Checker** (`src/typechecker/`) - Static type analysis
+5. **Interpreter** (`src/interpreter/`) - Executes AST with Tokio async runtime
+
+### Key Design Patterns
+
+- **Error Handling**: Comprehensive error types with codespan-reporting for user-friendly messages
+- **Async Operations**: Full Tokio integration for concurrent operations
+- **Standard Library**: Modular design in `src/stdlib/` with core, math, text, list, time, and pattern modules
+- **Configuration**: Hierarchical config system (global → local) in `src/config.rs` and `src/wfl_config/`
+- **Logging**: Dual logging system - standard logger and execution tracer using `exec_trace!` macro
+
+### Container System
+WFL uses "containers" (similar to classes) with:
+- Properties and actions (methods)
+- Inheritance support
+- Interface implementation
+- Event handling
+- Found in `src/parser/container_*.rs`
+
+### Natural Language Parsing
+The parser supports English-like syntax:
+- "store X as Y" for variable assignment
+- "check if X is greater than Y" for conditionals  
+- "count from X to Y" for loops
+- Function calls like "length of mylist"
+
 ## Standard Debug Procedure
 
 When debugging ANY issue:
@@ -71,18 +155,21 @@ When debugging ANY issue:
 4. Run static analyzer: `cargo run -- --analyze test.wfl`
 5. Fix issues and verify ALL existing tests still pass
 
-## Documentation Requirements
+## AI Development Rules
 
-Before making changes:
-1. Read `Docs/wfl-spec.md` for language specification
-2. Check module-specific docs in `Docs/`
-3. Review recent Dev Diary entries
-4. Consult memory bank files in `.kilocode/rules/memory-bank/`
+When working on this codebase:
 
-After making changes:
-1. Update relevant documentation
-2. Create Dev Diary entry with implementation details
-3. Add/update tests in appropriate locations
+1. **Never break existing functionality** - All changes must maintain backward compatibility
+2. **Follow the 6-step debug procedure** for any issues:
+   - Understand the issue
+   - Review code and logs
+   - Form hypothesis
+   - Make targeted change
+   - Test thoroughly
+   - Document in Dev diary
+3. **Test all changes** - Run the full test suite before considering work complete
+4. **Update Dev diary** - Create entries in `Dev diary/` for significant changes
+5. **Maintain clean separation** - Debug output uses `exec_trace!`, never pollutes program output
 
 ## Testing Requirements
 
@@ -96,72 +183,87 @@ After making changes:
 Run specific test: `cargo test test_name`
 Run module tests: `cargo test --package wfl --lib module_name`
 
-## Development Workflow
-
-1. **Understand the task**: Read all relevant documentation
-2. **Check existing code**: Search for similar patterns
-3. **Write tests first**: Add to TestPrograms/ or unit tests
-4. **Implement feature**: Follow existing code style
-5. **Run all tests**: `cargo test` and TestPrograms/
-6. **Check quality**: `cargo fmt` and `cargo clippy`
-7. **Update docs**: Modify relevant .md files
-8. **Create Dev Diary**: Document your implementation
-
-## CLI Flag Reference
+## Documentation Requirements
 
-| Flag | Description | Example |
-|------|-------------|---------|
-| `--lex` | Output lexer tokens only | `cargo run -- --lex program.wfl` |
-| `--parse` | Output AST only | `cargo run -- --parse program.wfl` |
-| `--lint` | Check code style | `cargo run -- --lint program.wfl` |
-| `--analyze` | Static analysis | `cargo run -- --analyze program.wfl` |
-| `--fix` | Auto-format code | `cargo run -- --fix program.wfl` |
-| `--in-place` | Modify file directly | `cargo run -- --fix program.wfl --in-place` |
-| `--check` | Dry run for --fix | `cargo run -- --fix program.wfl --check` |
-| `--debug` | Enable debug output | `cargo run -- --debug program.wfl` |
-| `--config` | Specify config file | `cargo run -- --config custom.wflcfg program.wfl` |
-| `--time` | Show execution time | `cargo run -- --time program.wfl` |
-| `-v, --version` | Show version info | `cargo run -- --version` |
+Before making changes:
+1. Read `Docs/wfl-spec.md` for language specification
+2. Check module-specific docs in `Docs/`
+3. Review recent Dev Diary entries
+4. Consult memory bank files in `.kilocode/rules/memory-bank/`
 
-## Architecture Overview
+After making changes:
+1. Update relevant documentation
+2. Create Dev Diary entry with implementation details
+3. Add/update tests in appropriate locations
 
-```
-Input (.wfl) → Lexer → Parser → Analyzer → Type Checker → Interpreter → Output
-                ↓       ↓         ↓           ↓              ↓
-              Tokens   AST    Validated   Type Info    Execution
-                              AST                       Results
-```
+## Critical Implementation Notes
 
-Key components:
-- **Lexer**: Token generation with Logos
-- **Parser**: Recursive descent, indentation-aware
-- **Analyzer**: Semantic validation, dead code detection
-- **Type Checker**: Static type analysis
-- **Interpreter**: Direct AST execution with async support
-- **Stdlib**: core, math, text, list, time, pattern modules
+### Parser Stability
+- The parser has comprehensive end token handling to prevent infinite loops
+- Always consume orphaned tokens during error recovery
+- Use `peek_token()` for lookahead, never `next_token()` unless consuming
 
-## Key Implementation Notes
+### Memory Management
+- Optional dhat heap profiling with `--features dhat-heap`
+- Careful lifetime management in parser to avoid borrow checker issues
+- Async operations properly handle cleanup
+- Variables stored in Environment HashMap
+- Scope management with push/pop
+- Automatic cleanup on scope exit
 
-### Error Handling
+### Error Reporting
+- All errors use the unified diagnostic system
+- Include source context with precise spans
+- Provide actionable suggestions when possible
 - Use `InterpreterError` for runtime errors
-- Include source location via spans
-- Provide helpful error messages with context
-
-### Async Operations
-- All I/O operations are async (web.get, file operations)
-- Use `await` keyword in WFL code
-- Tokio runtime handles execution
 
 ### Type System
 - Static typing with inference
 - Types: text, number, boolean, list, null, any
 - Function types for callbacks
 - Pattern matching with regex support
 
-### Memory Management
-- Variables stored in Environment HashMap
-- Scope management with push/pop
-- Automatic cleanup on scope exit
+### Async Operations
+- All I/O operations are async (web.get, file operations)
+- Use `await` keyword in WFL code
+- Tokio runtime handles execution
+
+## Common Workflows
+
+### Adding a New Feature
+1. Update the lexer if new tokens needed
+2. Extend the parser AST and parsing logic
+3. Add semantic analysis rules
+4. Implement type checking rules
+5. Add interpreter execution logic
+6. Write comprehensive tests
+7. Update documentation
+
+### Development Workflow
+1. **Understand the task**: Read all relevant documentation
+2. **Check existing code**: Search for similar patterns
+3. **Write tests first**: Add to TestPrograms/ or unit tests
+4. **Implement feature**: Follow existing code style
+5. **Run all tests**: `cargo test` and TestPrograms/
+6. **Check quality**: `cargo fmt` and `cargo clippy`
+7. **Update docs**: Modify relevant .md files
+8. **Create Dev Diary**: Document your implementation
+
+### Updating Standard Library
+1. Add function to appropriate module in `src/stdlib/`
+2. Register in module's `register_functions()`
+3. Add type signatures and validation
+4. Write tests in the module's test section
+5. Document in function catalog
+
+## Key Files to Understand
+
+- `src/parser/mod.rs` - Core parser logic and natural language handling
+- `src/interpreter/mod.rs` - Execution engine with async support
+- `src/stdlib/mod.rs` - Standard library registration
+- `src/diagnostics/mod.rs` - Error reporting system
+- `src/main.rs` - CLI entry point and command handling
+- `.kilocode/rules/` - Additional AI assistant context and rules
 
 ## Current Focus Areas (June 2025)
 
@@ -171,4 +273,4 @@ Key components:
 4. **Documentation**: Keeping all docs up-to-date
 5. **Stability**: Ensuring backward compatibility
 
-Remember: The goal is to make programming accessible while maintaining professional-grade tooling and performance.
+Remember: This is alpha software under active development. Always prioritize stability and backward compatibility while implementing new features. The goal is to make programming accessible while maintaining professional-grade tooling and performance.