1 files changed, 143 insertions, 0 deletions
diff --git a/js/scripting-lang/baba-yaga-c/ROADMAP.md b/js/scripting-lang/baba-yaga-c/ROADMAP.md
new file mode 100644
index 0000000..963c46f
--- /dev/null
+++ b/js/scripting-lang/baba-yaga-c/ROADMAP.md
@@ -0,0 +1,143 @@
+# Baba Yaga C Implementation Roadmap
+
+## Current Status
+- ✅ **Core Language**: Complete and stable (25/27 tests passing)
+- ✅ **Table Pattern Matching**: Fixed and working
+- ✅ **When Expressions**: Fixed and working
+- ✅ **Computed Table Keys**: Fixed and working (Task 1.1 complete)
+- ✅ **Multi-value Pattern Expressions**: Fixed and working (Task 1.2 complete)
+- ✅ **Pattern Matching Memory**: Fixed and working (Task 1.3 complete)
+- ✅ **Partial Application Support**: Fixed and working (Task 2.3 complete)
+- ❌ **2 Remaining Issues**: Test 22 parser issue, Integration Test 02 file reading issue
+
+## Quick Reference
+- **Test Command**: `./bin/baba-yaga tests/22_parser_limitations.txt`
+- **Key Files**: `src/parser.c` (parser_parse_when_pattern), `tests/22_parser_limitations.txt`
+- **Current Error**: `Parse error: Expected 'is' after test expression`
+- **Working Test**: `echo "test_multi_expr : x y -> when (x % 2) (y % 2) is 0 0 then \"both even\";" | ./bin/baba-yaga`
+
+## Implementation Plan
+
+### **Phase 1: Core Language Features** ✅ **COMPLETE**
+All core language features are now working correctly.
+
+### **Phase 2: Advanced Features** ✅ **COMPLETE**
+All advanced features including partial application are now working.
+
+### **Phase 3: Final Polish** 🔄 **IN PROGRESS**
+
+#### **Task 3.1: Test 22 Parser Issue** (Test 22) 🔍 **INVESTIGATED**
+**Issue**: `Parse error: Expected 'is' after test expression`
+**Current**: Core multi-value pattern functionality works correctly
+**Status**: Identified specific parser edge case - needs investigation
+
+**Investigation Findings**:
+- ✅ **Individual functions work**: Multi-value patterns parse and execute correctly when tested individually
+- ✅ **Isolated syntax works**: Same syntax works perfectly when tested via `echo`
+- ❌ **File-specific issue**: The error only occurs when the complete test file is processed
+- 🔍 **Parser edge case**: The issue appears to be in how the parser handles multiple patterns in sequence within a file context
+- 📍 **Error location**: Parser fails to recognize the `is` keyword in multi-value pattern context when processing the full file
+
+**Root Cause Analysis**:
+- The parser's `parser_parse_when_pattern` function may have an edge case when processing multiple patterns in sequence
+- The error suggests the parser is not correctly transitioning between pattern parsing states
+- This is likely a subtle parsing state management issue rather than a fundamental syntax problem
+
+#### **Task 3.2: Integration Test 02 File Reading** (Integration Test 02)
+**Issue**: Segmentation fault when reading file directly (works when piped)
+**Current**: Core pattern matching works, but file reading has issue
+**Status**: Need to fix file reading mechanism
+
+## **Recent Achievements**
+
+### **Task 2.3: Partial Application Support** ✅ **COMPLETE**
+- **Issue**: Test 17 failed with partial application and arity errors
+- **Solution**: Implemented proper partial application in function call mechanism
+- **Implementation**: 
+  - Modified `baba_yaga_function_call` to handle partial application
+  - Created `stdlib_partial_apply` helper function
+  - Updated `each` function to support partial application
+- **Result**: Test 17 now passes, 25/27 tests passing
+
+### **Task 1.2: Multi-value Pattern Expressions** ✅ **COMPLETE**
+- **Issue**: `when (x % 2) (y % 2) is` not supported
+- **Solution**: Enhanced parser to handle expressions in parentheses for multi-parameter patterns
+- **Implementation**: Added detection for multi-parameter patterns with expressions
+- **Result**: Multi-value pattern expressions now work correctly
+
+### **Task 1.3: Pattern Matching Memory** ✅ **COMPLETE**
+- **Issue**: Segmentation fault in complex pattern matching
+- **Solution**: Implemented sequence-to-sequence pattern matching for multi-parameter patterns
+- **Implementation**: Added element-by-element comparison logic for multi-parameter patterns
+- **Result**: Complex nested pattern matching now works correctly
+
+## **Next Priority**
+**Task 3.1**: Fix Test 22 parser edge case to achieve 26/27 tests passing
+**Task 3.2**: Fix Integration Test 02 file reading issue to achieve 27/27 tests passing
+
+## **Integration Test 02 Segfault Investigation**
+
+### Findings So Far
+- Recursive function calls (e.g., `factorial 5`) cause a segmentation fault **only when run from a file**, not when piped via `cat` or `echo`.
+- Non-recursive function calls, arithmetic, and function definitions all work as expected.
+- The segfault occurs instantly, not after deep recursion (not a stack overflow).
+- The function is defined in the global scope, and recursive lookup should work.
+- The bug is **not** in the recursion logic itself.
+
+### Hypothesis
+- The root cause is likely a memory or buffer issue in file reading, string handling, or tokenization.
+- There may be a difference in how the source buffer is loaded from a file vs. piped input (e.g., BOM, encoding, or invisible characters).
+
+### Next Steps
+1. Add debug output to print the raw contents of the buffer loaded by `read_file()` for `tests/integration_02_pattern_matching.txt` before it is passed to the interpreter.
+2. Compare the buffer content from file vs. piped input.
+3. Check for buffer overflows, uninitialized memory, or off-by-one errors in file reading and tokenization.
+4. Check for non-ASCII, BOM, or invisible characters in the test file.
+
+---
+
+## Technical Notes
+
+### **Partial Application Implementation**
+- **Function Call Mechanism**: Modified `baba_yaga_function_call` to detect insufficient arguments
+- **Partial Function Creation**: Creates new function with bound arguments stored in scope
+- **Argument Combination**: `stdlib_partial_apply` combines bound and new arguments
+- **Scope Management**: Uses temporary scope variables to store partial application data
+
+### **Pattern Matching Enhancements**
+- **Multi-parameter Support**: Handles `when (expr1) (expr2) is` syntax
+- **Sequence Comparison**: Element-by-element comparison for multi-value patterns
+- **Wildcard Support**: `_` pattern matches any value in multi-parameter contexts
+
+### **Parser Investigation Results**
+- **Multi-value patterns work correctly** in isolation and individual function definitions
+- **File processing edge case** identified in `parser_parse_when_pattern` function
+- **State management issue** suspected when processing multiple patterns in sequence
+- **Error occurs specifically** when the complete test file is processed, not in isolated tests
+
+### **Memory Management**
+- **Reference Counting**: Proper cleanup of function references
+- **Scope Cleanup**: Automatic cleanup of temporary scope variables
+- **Error Handling**: Graceful handling of memory allocation failures
+
+## Next Action
+**Continue with Task 3.1** (Test 22 Parser Issue) - investigate and fix the parser edge case in `parser_parse_when_pattern` function to achieve 26/27 tests passing.
+
+## Implementation Guide
+
+### **For Task 3.1: Test 22 Parser Issue**
+1. **Investigate `parser_parse_when_pattern` function**: Look for state management issues when processing multiple patterns
+2. **Debug the specific failing case**: Add debug output to understand why the parser fails to recognize `is` keyword
+3. **Fix the parser logic**: Update the parser to handle the edge case correctly
+4. **Test the fix**: Verify that Test 22 now passes
+
+### **For Task 3.2: Integration Test 02 File Reading**
+1. **Investigate the file reading issue**: Compare direct file reading vs piped input
+2. **Identify the root cause**: Find why direct file reading causes segmentation fault
+3. **Fix the file reading mechanism**: Update the file reading code to handle the issue
+4. **Test the fix**: Verify that Integration Test 02 now passes
+
+### **For CLI Ergonomics**
+1. **Simplify the REPL**: Make it more minimal and interactive
+2. **Improve error messages**: Better error reporting and debugging
+3. **Add helpful features**: Command history, line editing, etc.
\ No newline at end of file