a

Author: ghuntley

.cursor/rules.mdc

@@ -0,0 +1,100 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# Cursor AI Rules for CURSED Language Development
+
+The following rules are derived from studying the rust-hosted-langs/book repository, which provides guidance on implementing interpreters in Rust. These rules should be applied when assisting with the CURSED language implementation.
+
+## Memory Management
+
+1. **Use Custom Allocators**: For optimal performance and control, implement custom allocators rather than relying on Rust's standard collections.
+   - Follow the Sticky Immix pattern for efficient memory management
+   - Implement bump allocation for fast allocation paths
+   - Support block-based memory management for better locality
+
+2. **Safe Wrappers Over Unsafe Code**: Always create safe abstractions over unsafe memory operations.
+   - Encapsulate unsafe pointer operations in safe APIs
+   - Use proper lifetime annotations to prevent memory errors
+   - Implement RAII patterns for resource management
+
+3. **Tagged Pointers**: Utilize tagged pointers for efficient memory representation.
+   - Store type information in unused pointer bits
+   - Implement proper bit masking operations
+   - Ensure alignment requirements are met
+
+## Interpreter Design
+
+4. **Bytecode VM Architecture**: Implement a bytecode virtual machine for better performance.
+   - Design a compact instruction set
+   - Use efficient instruction dispatch methods
+   - Consider register vs. stack-based approaches
+
+5. **Multi-Stage Compilation**: Follow a clear pipeline from parsing to execution.
+   - Lexing → Parsing → AST → Bytecode → Execution
+   - Keep each stage modular and testable
+   - Consider adding optimization passes
+
+6. **Error Handling**: Implement robust error handling throughout the compiler and runtime.
+   - Use Result types consistently
+   - Provide meaningful error messages with location information
+   - Support error recovery where appropriate
+
+## Code Organization
+
+7. **Modular Component Design**: Structure code with clear module boundaries.
+   - Separate the allocator from the interpreter
+   - Use Rust modules to organize related functionality
+   - Define clear APIs between components
+
+8. **Testing Strategy**: Implement comprehensive testing at multiple levels.
+   - Unit tests for individual components
+   - Integration tests for the full pipeline
+   - Regression tests for fixed bugs
+   - Fuzzing for parser robustness
+
+9. **Documentation**: Document code thoroughly, especially for unsafe operations.
+   - Explain the "why" behind complex algorithms
+   - Document invariants and assumptions
+   - Include examples in public API documentation
+
+## Rust-Specific Practices
+
+10. **Unsafe Code Minimization**: Contain unsafe code to the smallest possible scope.
+    - Use unsafe blocks only when necessary
+    - Validate all preconditions before unsafe operations
+    - Document safety requirements extensively
+
+11. **Performance Considerations**: Be mindful of Rust-specific performance patterns.
+    - Avoid unnecessary allocations and cloning
+    - Use references instead of owned values where appropriate
+    - Consider inlining critical paths
+
+12. **Gen Z Slang Consistent Implementation**: Ensure consistency in the translation of Go-like syntax to Gen Z slang.
+    - Maintain a comprehensive mapping table between Go keywords and CURSED equivalents
+    - Apply consistent naming conventions throughout the codebase
+    - Keep slang usage authentic to Gen Z terminology
+
+## Building Process
+
+13. **Use Make for Build Commands**: Always use Make as the primary build interface.
+    - Use `make build` instead of direct `cargo build` commands
+    - Use `make test` instead of direct `cargo test` commands
+    - Keep the Makefile up to date with all necessary build tasks
+
+14. **Maintain Specs**: Keep specs documentation current with implementation.
+    - Update specs when language features change
+    - Ensure examples in specs are valid and tested
+    - Cross-reference specs with implementation
+
+15. **Bootstrapping Process**: Follow the defined bootstrapping stages.
+    - Stage 0: Environment setup
+    - Stage 1: Bootstrap compiler in Rust
+    - Stage 2: Full compiler in CURSED
+    - Stage 3: Self-compiled compiler 
+
+16. **Implementation Status**: As the compiler is implemented
+    - Study IMPLEMENTATION_STATUS.md to determine next steps
+    - Update IMPLEMENTATION_STATUS.md when a step is complete
+    - Use IMPLEMENTATION_STATUS.md to track what you need to do next 

.envrc

@@ -0,0 +1,5 @@
+export DIRENV_WARN_TIMEOUT=20s
+
+eval "$(devenv direnvrc)"
+
+use devenv

.gitignore

@@ -0,0 +1,11 @@
+/target
+
+# Devenv
+.devenv*
+devenv.local.nix
+
+# direnv
+.direnv
+
+# pre-commit
+.pre-commit-config.yaml