taurus 0.1.0

data/docs/v1.0.0_CONTINUATION_PROMPT.md

@@ -0,0 +1,382 @@
+# Taurus v1.0.0 - Session 1 Continuation Prompt
+
+**Date**: 2024-12-05  
+**Current Version**: 0.9.0 (Released)  
+**Target Version**: 1.0.0  
+**Current Session**: Session 1 of 12  
+**Current Feature**: Enhanced Error Messages  
+**Current Phase**: Phase 1 - Error Infrastructure
+
+## Context
+
+Taurus v0.9.0 has been successfully released with:
+- ✅ Custom namespace API (Ruby layer)
+- ✅ XPath performance optimizations (2-3× faster)
+- ✅ Complete benchmarking (all 27 XPath functions)
+- ✅ All tests passing (16/16)
+- ✅ Documentation complete
+
+v1.0.0 will add three major features:
+1. **Enhanced Error Messages** (Foundation - Week 1)
+2. **C-Level Namespace Registry** (Performance - Week 2)
+3. **SAX Parser Interface** (Enterprise Scale - Week 3)
+
+## Session 1 Objective
+
+**Feature**: Enhanced Error Messages  
+**Phase**: Phase 1 - Error Infrastructure  
+**Time**: 2 hours  
+**Priority**: 🔥 High (Foundation for all other features)
+
+### Goals
+1. Create error infrastructure in C (`errors.c`, `errors.h`)
+2. Define error codes and context structure
+3. Implement basic error creation/retrieval API
+4. Add FFI bindings for error extraction
+5. Test basic error flow
+
+### Success Criteria
+- [ ] `lib/src/errors.c` created (~400 lines)
+- [ ] `lib/src/errors.h` created (~100 lines)
+- [ ] 15+ error codes defined
+- [ ] `TaurusError` struct with context fields
+- [ ] FFI bindings working
+- [ ] Basic tests passing
+- [ ] Zero memory leaks
+
+## Planning Documents
+
+**MUST READ** before starting:
+1. [`docs/v1.0.0_CONTINUATION_PLAN.md`](v1.0.0_CONTINUATION_PLAN.md) - Complete feature plan
+2. [`docs/v1.0.0_STATUS_TRACKER.md`](v1.0.0_STATUS_TRACKER.md) - Current progress
+3. [`docs/v0.9.0_RELEASE_SUMMARY.md`](v0.9.0_RELEASE_SUMMARY.md) - What was just completed
+
+## Implementation Steps
+
+### Step 1: Create Error Header (30 min)
+
+Create `lib/src/errors.h`:
+
+```c
+#ifndef TAURUS_ERRORS_H
+#define TAURUS_ERRORS_H
+
+#include <stddef.h>
+#include <stdbool.h>
+
+// Error codes (add more as needed)
+typedef enum {
+    TAURUS_ERROR_NONE = 0,
+    
+    // Parse errors (1xx)
+    TAURUS_ERROR_PARSE_UNCLOSED_TAG = 100,
+    TAURUS_ERROR_PARSE_INVALID_ATTR = 101,
+    TAURUS_ERROR_PARSE_ENCODING = 102,
+    TAURUS_ERROR_PARSE_NAMESPACE = 103,
+    TAURUS_ERROR_PARSE_MALFORMED = 104,
+    
+    // XPath errors (2xx)
+    TAURUS_ERROR_XPATH_SYNTAX = 200,
+    TAURUS_ERROR_XPATH_FUNCTION = 201,
+    TAURUS_ERROR_XPATH_TYPE_MISMATCH = 202,
+    TAURUS_ERROR_XPATH_NAMESPACE = 203,
+    TAURUS_ERROR_XPATH_UNKNOWN_AXIS = 204,
+    
+    // Evaluation errors (3xx)
+    TAURUS_ERROR_EVAL_CONTEXT = 300,
+    TAURUS_ERROR_EVAL_ARGUMENT = 301,
+    TAURUS_ERROR_EVAL_OVERFLOW = 302,
+    
+    // Generic errors (9xx)
+    TAURUS_ERROR_OUT_OF_MEMORY = 900,
+    TAURUS_ERROR_INTERNAL = 999
+} TaurusErrorCode;
+
+// Error context structure
+typedef struct {
+    TaurusErrorCode code;
+    char* message;              // Primary error message
+    char* context_snippet;      // Code snippet around error (optional)
+    int line;                   // Line number (1-based, 0 if N/A)
+    int column;                 // Column number (1-based, 0 if N/A)
+    size_t byte_offset;         // Byte offset in input (0 if N/A)
+} TaurusError;
+
+// Error API
+TaurusError* taurus_error_create(TaurusErrorCode code, const char* message);
+TaurusError* taurus_error_create_with_context(
+    TaurusErrorCode code,
+    const char* message,
+    const char* input,
+    size_t byte_offset,
+    int line,
+    int column
+);
+void taurus_error_free(TaurusError* error);
+const char* taurus_error_get_message(TaurusError* error);
+const char* taurus_error_get_full_message(TaurusError* error);
+
+// Global error state (thread-local in future)
+void taurus_error_set(TaurusError* error);
+TaurusError* taurus_error_get(void);
+void taurus_error_clear(void);
+bool taurus_error_has_error(void);
+
+#endif // TAURUS_ERRORS_H
+```
+
+**Checklist**:
+- [ ] File created
+- [ ] Error codes defined (15+)
+- [ ] `TaurusError` struct defined
+- [ ] API functions declared
+- [ ] Global error state functions declared
+
+### Step 2: Implement Error Functions (60 min)
+
+Create `lib/src/errors.c`:
+
+**Key Functions**:
+1. `taurus_error_create()` - Basic error creation
+2. `taurus_error_create_with_context()` - Error with line/column
+3. `taurus_error_free()` - Memory cleanup
+4. `taurus_error_get_message()` - Get basic message
+5. `taurus_error_get_full_message()` - Get formatted message with context
+6. Global error state management
+
+**Context Snippet Extraction**:
+```c
+static char* extract_context_snippet(const char* input, size_t offset, int line) {
+    // Extract ±2 lines around error
+    // Format with line numbers
+    // Highlight error position with ^
+    return formatted_snippet;
+}
+```
+
+**Message Formatting**:
+```c
+const char* taurus_error_get_full_message(TaurusError* error) {
+    // Format: "message at line X, column Y\n\nContext:\n<snippet>"
+    // Reuse allocated buffer or create new one
+    return formatted_message;
+}
+```
+
+**Checklist**:
+- [ ] All functions implemented
+- [ ] Memory management correct (no leaks)
+- [ ] Context snippet extraction works
+- [ ] Message formatting includes line/column
+- [ ] Global error state works
+- [ ] Code compiles cleanly
+
+### Step 3: Add FFI Bindings (20 min)
+
+Update `lib/taurus/ffi/errors.rb`:
+
+```ruby
+module Taurus
+  module FFI
+    # Error code enum
+    module ErrorCode
+      NONE = 0
+      PARSE_UNCLOSED_TAG = 100
+      PARSE_INVALID_ATTR = 101
+      # ... etc
+    end
+    
+    # Error struct
+    class ErrorStruct < ::FFI::Struct
+      layout :code, :int,
+             :message, :string,
+             :context_snippet, :string,
+             :line, :int,
+             :column, :int,
+             :byte_offset, :size_t
+    end
+    
+    # FFI bindings
+    attach_function :taurus_error_get, [], ErrorStruct.ptr
+    attach_function :taurus_error_clear, [], :void
+    attach_function :taurus_error_has_error, [], :bool
+    attach_function :taurus_error_free, [ErrorStruct.ptr], :void
+  end
+  
+  module ErrorHandling
+    def self.check_error!
+      return unless FFI.taurus_error_has_error
+      
+      error_ptr = FFI.taurus_error_get
+      return if error_ptr.null?
+      
+      error = error_ptr.read_pointer
+      code = error[:code]
+      message = error[:message]
+      line = error[:line]
+      column = error[:column]
+      context = error[:context_snippet]
+      
+      FFI.taurus_error_clear
+      
+      # Raise appropriate Ruby exception
+      raise create_ruby_error(code, message, line, column, context)
+    end
+    
+    private
+    
+    def self.create_ruby_error(code, message, line, column, context)
+      # Map C error codes to Ruby error classes
+      # Add context information
+    end
+  end
+end
+```
+
+**Checklist**:
+- [ ] Error struct defined in FFI
+- [ ] Error codes mapped
+- [ ] Bindings attached
+- [ ] `check_error!` implemented
+- [ ] Error extraction works
+
+### Step 4: Basic Testing (10 min)
+
+Create `spec/taurus/errors_spec.rb`:
+
+```ruby
+RSpec.describe "Error Infrastructure" do
+  describe "C error creation" do
+    it "creates basic error"
+    it "creates error with context"
+    it "extracts line/column"
+    it "formats context snippet"
+  end
+  
+  describe "FFI bridging" do
+    it "extracts error from C"
+    it "maps error codes correctly"
+    it "clears error state"
+  end
+  
+  describe "Memory management" do
+    it "frees error memory"
+    it "no memory leaks" # Run with valgrind
+  end
+end
+```
+
+**Checklist**:
+- [ ] Test file created
+- [ ] Basic tests passing
+- [ ] FFI tests passing
+- [ ] Memory tests passing (valgrind clean)
+
+## File Checklist
+
+### New Files
+- [ ] `lib/src/errors.c` (~400 lines)
+- [ ] `lib/src/errors.h` (~100 lines)
+- [ ] `lib/taurus/ffi/errors.rb` (enhanced, ~100 lines added)
+- [ ] `spec/taurus/errors_spec.rb` (~100 lines)
+
+### Modified Files
+- [ ] `lib/src/Makefile` or `CMakeLists.txt` (add errors.c)
+- [ ] `lib/taurus/ffi.rb` (require errors.rb)
+
+## Build & Test Commands
+
+```bash
+# Compile C library
+cd build
+cmake .. && make
+
+# Run Ruby tests
+cd ..
+bundle exec rspec spec/taurus/errors_spec.rb
+
+# Memory leak check
+valgrind --leak-check=full bundle exec rspec spec/taurus/errors_spec.rb
+
+# Full test suite
+bundle exec rspec
+```
+
+## Success Verification
+
+Before completing session:
+- [ ] All new files created
+- [ ] Code compiles without errors
+- [ ] Tests pass (at least basic error creation)
+- [ ] No memory leaks (valgrind clean)
+- [ ] Documentation comments in code
+- [ ] Status tracker updated
+
+## Architecture Principles (CRITICAL)
+
+**MUST FOLLOW**:
+1. **MECE** - Errors mutually exclusive, collectively exhaustive
+2. **Object-Oriented** - Error objects, not static strings
+3. **Separation of Concerns** - C errors, FFI bridge, Ruby exceptions separate
+4. **No Code Guards** - Architectural solutions, not `#ifdef`
+5. **Single Responsibility** - Each function does one thing
+6. **Clean Memory** - ALL allocations must be freed
+
+**File Size Limits**:
+- Target: ≤700 lines per file
+- Maximum: 800 lines per file
+- Current plan: errors.c (400), errors.h (100) ✅
+
+## Common Pitfalls to Avoid
+
+1. **Don't** use static buffers for messages (memory leaks)
+2. **Don't** forget to free error context snippets
+3. **Don't** use `printf` for error messages (use allocation)
+4. **Don't** hardcode error messages (use error codes + formatting)
+5. **Don't** skip memory leak testing (valgrind is required)
+
+## Next Session Preview
+
+**Session 2**: Phase 2 - Parse Error Enhancement
+- Enhance `parse_simple.c` with line/column tracking
+- Implement context snippet extraction for XML
+- Create Ruby `ParseError` classes
+- Test parse error scenarios
+
+**Estimated Time**: 2 hours
+
+## Questions to Consider
+
+1. Should we use thread-local storage for error state?
+2. Should error context snippets be limited in size?
+3. Should we cache error strings or compute each time?
+4. Should we include stack traces in internal errors?
+
+**Default Answers** (for now):
+1. No - single-threaded first, add later if needed
+2. Yes - max 200 chars per snippet
+3. Compute each time - cleaner memory model
+4. No - keep errors simple and clear
+
+## Reference Documentation
+
+- **C Error Patterns**: See `old-docs/` for historical approaches
+- **FFI Examples**: See existing `lib/taurus/ffi/bridge.rb`
+- **Test Patterns**: See existing `spec/taurus/element_spec.rb`
+
+## Final Checklist
+
+Before marking Phase 1 complete:
+- [ ] All code written and tested
+- [ ] valgrind shows zero leaks
+- [ ] Code follows MECE principles
+- [ ] Architecture is clean and extensible
+- [ ] Documentation comments complete
+- [ ] Status tracker updated
+- [ ] Ready for Phase 2
+
+---
+
+**Ready to begin Session 1: Enhanced Error Messages - Phase 1!** 🚀
+
+Start by reading the three planning documents listed above, then proceed with Step 1.