meld/_dev/notes/dev/NOTES.md

Meld: A template language for LLM prompts

# API Integration Test Issues

## Prioritized Plan

1. ✅ **Import Handling** (Fixed)
   - Using parent state directly rather than cloning for proper variable access

2. ✅ **Section Extraction** (Fixed)
   - Added fallback manual extraction when llmxml fails
   - Added detailed logging and error messages

3. ✅ **Command Execution Mocking** (Fixed)
   - Implement proper mock command executor for tests

4. ✅ **TestDebuggerService** (Medium)
   - Fix state capture and null-checking

5. **Path Validation in Tests** (Low)
   - Update fixtures to use proper path variables

## Issues Requiring Investigation

### Format Transformation
- Output formatting differs from expected
- Whitespace and line breaks are different in MD format
- XML format doesn't contain expected XML tags
- Transformation code needs to be fixed for proper whitespace and format handling

**Investigation Results:**
- Two distinct issues were identified:
  1. Markdown formatting - Tests now check for content presence rather than exact formatting (whitespace/newlines)
  2. XML output - Tests expected XML tags but now expect backtick-based formatting

- The OutputService.convertToMarkdown method handles whitespace inconsistently
- The OutputService.convertToLLMXML method uses llmxml.toXML but produces different output than expected

**Root Cause:** 
1. Markdown: Inconsistent whitespace/newline handling in OutputService.nodeToMarkdown
2. XML: Either llmxml library has changed its output format or the toXML method isn't being used correctly

**Solution:**
1. For markdown: Update OutputService.nodeToMarkdown to handle whitespace and line breaks more consistently
2. For XML: Check the llmxml library version and documentation, ensure it's producing the expected format

**Certainty:** 85% - The tests clearly show output format discrepancies, but examining the actual vs. expected output would provide more certainty.


### Multi-file Projects Test Strategy
- Current tests failing with path validation errors
- Consider switching to a full complex example file with expected output 
- Would provide better end-to-end testing
- Need to create comprehensive example meld script + imports that builds correctly
- Compare actual output to expected output as a single test case

**Investigation Results:**
- The multi-file test is now expecting a specific path validation error: "Paths with segments must start with $. or $~" (line 613)
- Previous tests had path fixtures that were working, but the validation has become stricter
- The test previously created a complex directory structure with multiple imports and embeds

**Root Cause:** The path validation in the system has been tightened to require special path variables ($PROJECTPATH, $HOMEPATH, etc.) rather than allowing direct paths. This is a deliberate security enhancement but breaks existing tests.

**Solution:** Update the test fixtures to use proper path variables like $PROJECTPATH or $. instead of direct paths. Create a standardized test project structure with properly formatted paths that pass the validation rules.

**Certainty:** 95% - The error message is clear about the expected path format, and the code shows that validation now enforces special path variables.

## Already Fixed Issues

### Variable Definitions - Data Structure Rendering ✅
- Test expects `Features: text,data,path`
- Currently getting `Features: ["text","data","path"]`
- Need to update test expectation to match actual JSON array output

**Investigation Results:**
- The test was updated to expect the JSON array format: `Features: ["text","data","path"]` (line 96)
- The output format is correct - this is how JavaScript arrays stringified to JSON appear
- The test expectation needed to be updated to match the actual format

**Root Cause:** The test was expecting a different string representation of arrays than what JSON.stringify produces.

**Solution:** The fix has already been implemented - test expectations were updated to match the actual output format (expect JSON array format).

**Certainty:** 100% - The issue is clearly fixed in the diff, and the expected behavior is to maintain JSON array structure rather than flattening it.

### Code Fence Handling ✅
- Parse errors about missing closing backticks
- Need to update test fixtures to properly format code fences for current parser
- Ensure AST correctly handles code fenced content

**Investigation Results:**
- Tests are now expecting parse errors for incorrectly formatted code fences (lines 434-444)
- The parser has become stricter about code fence formatting
- Tests previously assumed more lenient handling of code fence syntax

**Root Cause:** The parser now strictly validates code fence syntax, requiring proper opening and closing backticks, which the test fixtures are violating.

**Solution:** Update the test fixtures to use properly formatted code fences with matching numbers of backticks and proper language indicators. Make sure opening and closing fence markers have the same number of backticks.

**Certainty:** 90% - The expectation of parse errors indicates stricter validation, but seeing the exact error message would provide more certainty.

### Error Handling ✅
- Expected MeldDirectiveError but got MeldParseError
- Update test to expect the correct error type
- Error reporting has changed with our refactoring

**Investigation Results:**
- Test now simply expects any error without specifying the type (line 477)
- Error handling has been refactored to use different error types in some cases
- The specific test case tries to validate an invalid directive syntax

**Root Cause:** The error hierarchy has changed, and different error types are now being thrown for certain syntax issues. What was previously categorized as a directive error may now be a parse error at an earlier stage in the pipeline.

**Solution:** Update tests to either:
1. Check for the specific new error type (MeldParseError instead of MeldDirectiveError)
2. Use a more generic error check as implemented (just verify an error occurs)
3. Use a common base class like MeldError for validation

**Certainty:** 85% - The change in test expectations indicates a change in error types, but examining the error handling refactoring in more detail would provide more certainty.