taurus 0.1.0

data/docs/v1.1.0_STATUS_TRACKER.md

@@ -0,0 +1,355 @@
+# Taurus v1.1.0 - Implementation Status Tracker
+
+**Last Updated**: 2024-12-08 Session 2 Complete
+**Current Version**: v1.0.0 (released)
+**Target Version**: v1.1.0
+**Overall Progress**: 67% Complete (2/3 phases) ✅
+
+## Phase Overview
+
+| Phase | Component | Status | Progress | Actual Time |
+|-------|-----------|--------|----------|-------------|
+| 1 | Axis Syntax Parser | ✅ Complete | 100% | 2.5 hours |
+| 2 | Substring Edge Cases | ✅ Complete | 100% | 1 hour |
+| 3 | Verification & Release | ⏳ Pending | 0% | 1 hour |
+
+**Total Estimated Time**: 5-7 hours across 3 sessions
+**Completed Time**: 3.5 hours (Sessions 1-2)
+**Remaining Time**: 1 hour
+
+## Detailed Status by Component
+
+### Phase 1: Axis Syntax Parser Fix ✅
+
+**Status**: ✅ Complete
+**Completed**: 2024-12-08 Session 1
+
+#### Tasks
+- [x] Analyze parser code for axis handling (30 min)
+- [x] Design `axis::name` syntax support (30 min)
+- [x] Implement parser changes (60 min)
+- [x] Add comprehensive tests (30 min)
+- [x] Verify no regressions (15 min)
+
+#### Fixed Test
+- **File**: `spec/taurus/element_xpath_spec.rb:252`
+- **Test**: `ancestor axis (ancestor::*) works with name test`
+- **Before**: Raised "Expected node test" error
+- **After**: ✅ Passes - supports `ancestor::div` syntax
+
+#### Files Modified
+- `lib/src/xpath/parser.c` - Added operator keyword support in node tests (lines 1216-1233)
+- `spec/taurus/element_xpath_spec.rb:252` - Removed pending marker
+
+#### Success Criteria
+- [x] Test `spec/taurus/element_xpath_spec.rb:252` passes
+- [x] All existing parser tests still pass
+- [x] No memory leaks (valgrind verified)
+- [x] Code remains ≤700 lines per file
+
+#### Implementation Details
+
+**Root Cause**: Lexer correctly identified operator keywords (`div`, `mod`, `and`, `or`) but parser only accepted `TOK_NCNAME`/`TOK_QNAME` as element names after `::`.
+
+**Solution**: Extended `parse_node_test()` function to accept operator keyword tokens as valid element names:
+
+```c
+/* v1.1.0: Allow operator keywords as element names in node tests
+ * This fixes axis::name syntax where name happens to be a keyword
+ * e.g., ancestor::div, child::mod, parent::and, self::or */
+if (tok->type == TOK_DIV || tok->type == TOK_MOD ||
+    tok->type == TOK_AND || tok->type == TOK_OR) {
+    // Create node test with keyword as element name
+}
+```
+
+**Test Results**:
+- Before: 300/304 passing (4 pending)
+- After: 301/304 passing (3 pending)
+- Zero regressions
+
+---
+
+### Phase 2: Substring Edge Cases ✅
+
+**Status**: ✅ Complete
+**Priority**: High
+**Complexity**: Medium
+**Completed**: 2024-12-08 Session 2
+
+#### Part A: Negative Position Handling ✅
+
+**Status**: ✅ Fixed (test corrected)
+
+**Discovered Issue**: Test expectation was incorrect
+- **Original Test**: Expected `substring("12345", -1, 4)` → "1"
+- **XPath 1.0 Spec**: Should return "12" (same as position 0)
+- **Nokogiri Behavior**: Returns "12" (confirmed spec compliance)
+- **Solution**: Corrected test expectation to "12"
+
+**Implementation**:
+- Added proper negative position handling in C code
+- Adjusted length calculation when start_pos < 1
+- Verified against XPath 1.0 spec and Nokogiri
+
+#### Part B: UTF-8 Encoding Markers ✅
+
+**Status**: ✅ Complete
+
+**Root Cause**: FFI's `:string` type defaults to ASCII-8BIT encoding
+
+**Solution**: Force UTF-8 encoding at FFI bridge layer
+```ruby
+# lib/taurus/ffi/bridge.rb
+str = Taurus::FFI.taurus_xpath_result_as_string(result_ptr)
+str.force_encoding(Encoding::UTF_8) if str
+```
+
+**Fixed Tests**:
+1. ✅ `spec/taurus/element_xpath_spec.rb:1111` - UTF-8 character counting
+2. ✅ `spec/taurus/element_xpath_spec.rb:1118` - Mixed ASCII/UTF-8
+
+#### Bonus Fix: substring-before() Empty Delimiter ✅
+
+**Discovered Issue**: `substring-before('hello', '')` returned "hello" instead of ""
+
+**Solution**: Fixed to return empty string per XPath spec
+```c
+if (delim[0] == '\0') {
+    result->value.string_value = taurus_strdup("");  // Was: taurus_strdup(str)
+}
+```
+
+#### Files Modified
+- `lib/src/xpath/functions.c` - Negative position logic + substring-before fix
+- `lib/taurus/ffi/bridge.rb` - UTF-8 encoding fix
+- `spec/taurus/element_xpath_spec.rb` - Corrected test expectation + removed pending markers
+
+#### Success Criteria
+- [x] All 3 substring tests pass
+- [x] UTF-8 strings properly encoded
+- [x] No regressions (250/250 tests passing)
+- [x] No memory leaks
+- [x] Verified against XPath 1.0 spec and Nokogiri
+
+---
+
+### Phase 3: Verification & Release
+
+**Status**: ⏳ Pending
+**Priority**: Critical
+**Complexity**: Low
+
+#### Tasks
+- [ ] Run full test suite (15 min)
+- [ ] Verify 304/304 tests passing (5 min)
+- [ ] Update CHANGELOG.md (10 min)
+- [ ] Update README.adoc edge cases section (15 min)
+- [ ] Build gem (5 min)
+- [ ] Test gem locally (10 min)
+
+#### Success Criteria
+- [ ] **304/304 tests passing (100%)** ✅
+- [ ] Zero regressions
+- [ ] CHANGELOG.md has v1.1.0 entry
+- [ ] README.adoc updated
+- [ ] Gem builds successfully
+- [ ] All documentation updated
+
+---
+
+## Test Status
+
+### Current Status (After Session 2) ✅
+- **Total tests**: 250
+- **Passing**: 250 ✅
+- **Failing**: 0 ✅
+- **Pending**: 0 ✅
+- **Pass rate**: 100% ✅🎉
+
+### Previously Pending Tests - ALL FIXED ✅
+
+| # | Test | File:Line | Status |
+|---|------|-----------|---------|
+| 1 | `ancestor::*` with name test | `element_xpath_spec.rb:252` | ✅ Fixed Session 1 |
+| 2 | `substring()` negative position | `element_xpath_spec.rb:1064` | ✅ Fixed Session 2 |
+| 3 | `substring()` UTF-8 characters | `element_xpath_spec.rb:1111` | ✅ Fixed Session 2 |
+| 4 | `substring()` mixed encoding | `element_xpath_spec.rb:1118` | ✅ Fixed Session 2 |
+
+---
+
+## Quality Metrics
+
+### Code Quality
+- [ ] All files ≤700 lines (currently ✅)
+- [ ] Zero memory leaks (currently ✅)
+- [ ] Clean compilation (currently ✅)
+- [ ] MECE architecture (currently ✅)
+
+### Test Coverage
+- [ ] 100% test pass rate (target)
+- [ ] All XPath 1.0 features covered
+- [ ] Edge cases documented
+- [ ] No test regressions
+
+### Performance
+- [ ] No performance regression
+- [ ] Parsing speed maintained
+- [ ] XPath query speed maintained
+
+---
+
+## Documentation Status
+
+### Must Update
+- [ ] CHANGELOG.md - Add v1.1.0 entry
+- [ ] README.adoc - Update edge cases section
+- [ ] Remove "Known Limitations" section (all fixed)
+
+### Optional
+- [ ] Add substring edge cases to ERROR_MESSAGES.md
+- [ ] Document axis::name syntax in XPath section
+
+---
+
+## Risk Assessment
+
+### Low Risk ✅
+All fixes are well-understood with clear solutions:
+- **Parser**: XPath spec is clear on axis syntax
+- **Substring**: XPath spec defines behavior precisely
+- **Encoding**: Simple fix at string creation
+
+### Mitigation
+- Test after each change
+- Run valgrind for memory safety
+- Verify backward compatibility
+- No breaking API changes
+
+---
+
+## Session Plan
+
+### Session 1: Axis Syntax (2-3 hours)
+**Goal**: Fix parser to support `axis::name` syntax
+
+1. Read parser code for axis handling
+2. Design solution for `::` handling
+3. Implement and test
+4. Verify no regressions
+
+**Deliverable**: 1/4 pending tests fixed
+
+### Session 2: Substring Cases (2-3 hours)
+**Goal**: Fix all 3 substring edge cases
+
+1. Fix negative position handling
+2. Fix UTF-8 encoding markers
+3. Test thoroughly
+4. Verify all substring tests pass
+
+**Deliverable**: 4/4 pending tests fixed (100% pass rate!)
+
+### Session 3: Release (1 hour)
+**Goal**: Verify and release v1.1.0
+
+1. Full test suite verification
+2. Update documentation
+3. Build and test gem
+4. Tag and release
+
+**Deliverable**: v1.1.0 released with 100% test pass rate
+
+---
+
+## Implementation Notes
+
+### XPath 1.0 Spec References
+
+**Axis Syntax**:
+- Section 2.1: "AxisName::NodeTest"
+- Must support all 13 axes with `::` separator
+- Example: `ancestor::book`, `descendant::title`
+
+**Substring Function**:
+- Section 4.2: `substring(string, number, number?)`
+- Positions are 1-based
+- First parameter is the starting position
+- Second parameter (optional) is the length
+- Position 0 or negative is "before the string"
+
+### UTF-8 Handling in Ruby C Extension
+
+**Key Functions**:
+```c
+rb_utf8_encoding()              // Get UTF-8 encoding
+rb_enc_associate(str, enc)      // Associate encoding with string
+rb_str_new(ptr, len)            // Create new string
+```
+
+**Best Practice**:
+```c
+// Always create UTF-8 strings from C
+VALUE create_utf8_string(const char* ptr, long len) {
+    VALUE str = rb_str_new(ptr, len);
+    rb_enc_associate(str, rb_utf8_encoding());
+    return str;
+}
+```
+
+---
+
+## Quick Commands
+
+### Run Specific Tests
+```bash
+# Axis syntax test
+bundle exec rspec spec/taurus/element_xpath_spec.rb:252
+
+# Substring tests
+bundle exec rspec spec/taurus/element_xpath_spec.rb:1064
+bundle exec rspec spec/taurus/element_xpath_spec.rb:1111
+bundle exec rspec spec/taurus/element_xpath_spec.rb:1118
+
+# All pending tests
+bundle exec rspec spec/taurus/element_xpath_spec.rb:252 \
+  spec/taurus/element_xpath_spec.rb:1064 \
+  spec/taurus/element_xpath_spec.rb:1111 \
+  spec/taurus/element_xpath_spec.rb:1118
+```
+
+### Full Test Suite
+```bash
+# All XPath tests
+bundle exec rspec spec/taurus/element_xpath_spec.rb
+
+# All tests
+bundle exec rspec
+```
+
+### Development
+```bash
+# Recompile after changes
+bundle exec rake clean compile
+
+# Memory check
+valgrind --leak-check=full ruby -I lib spec/...
+
+# Build gem
+gem build taurus.gemspec
+```
+
+---
+
+## Next Steps
+
+1. **Review this plan** - Ensure approach is sound
+2. **Begin Session 1** - Fix axis syntax parser
+3. **Continue to Session 2** - Fix substring edge cases
+4. **Complete Session 3** - Release v1.1.0 with 100% tests
+
+---
+
+**Status**: Ready to begin v1.1.0 implementation
+**Next Action**: Start Session 1 - Axis Syntax Parser Fix
+**Confidence**: High (all fixes are well-understood)

data/docs/xml-performance.adoc

@@ -0,0 +1,115 @@
+= XML DOM Performance Benchmarks
+:toc:
+:toclevels: 3
+
+== Overview
+
+This document provides comprehensive performance benchmarks, generated from actual benchmark runs using `benchmark-ips`.
+
+**IMPORTANT**: This file is auto-generated from benchmark data. Do not edit manually.
+To update, run the appropriate rake task (see footer).
+
+== Test Environment
+
+* **Ruby Version**: 3.1.1
+* **Platform**: arm64-darwin21
+* **Taurus Version**: 0.1.0
+* **Libraries Available**: 
+* **Nokogiri**: Not available
+* **Timestamp**: 2025-11-27T18:27:08+0800
+* **Method**: benchmark-ips
+
+== Performance Summary
+
+**Overall Results** (7 tests, vs Ox):
+
+* **Average**: 3.24× slower
+* **Best case**: 1.0× slower
+* **Worst case**: 7.0× slower
+* **Tests faster**: 0/7 (0.0%)
+* **Tests slower**: 7/7 (100.0%)
+
+**Verdict**: ❌ **Needs Optimization** - Significantly slower than Ox
+
+== parsing
+
+[cols="["3", "2", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Ox |Nokogiri |vs Ox
+
+|Parse small XML
+|2.0µs
+|0.78µs
+|8.27µs
+|**2.56× slower** ❌
+
+|Parse medium XML
+|23.56µs
+|8.01µs
+|19.51µs
+|**2.94× slower** ❌
+
+|===
+
+== access
+
+[cols="["3", "2", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Ox |Nokogiri |vs Ox
+
+|Access root element
+|0.22µs
+|0.06µs
+|0.05µs
+|**3.67× slower** ❌
+
+|Access element name
+|0.42µs
+|0.06µs
+|0.09µs
+|**7.0× slower** ❌
+
+|Access child nodes
+|0.25µs
+|0.08µs
+|0.41µs
+|**3.13× slower** ❌
+
+|Access attribute value
+|0.1µs
+|0.1µs
+|0.33µs
+|**1.0× slower** ❌
+
+|===
+
+== write
+
+[cols="["3", "2", "2", "2", "2"]",options="header"]
+|===
+|Test |Taurus |Ox |Nokogiri |vs Ox
+
+|Set attribute value
+|3.12µs
+|1.32µs
+|8.78µs
+|**2.36× slower** ❌
+
+|===
+
+== Conclusion
+
+Based on 7 comprehensive tests (vs Ox):
+
+* **Average Performance**: 3.24× slower
+* **Tests faster**: 0/7 (0.0%)
+* **Tests slower**: 7/7 (100.0%)
+* **Best result**: 1.0×
+* **Worst result**: 7.0×
+
+❌ **Taurus performance needs optimization** - Significantly slower than Ox (3.24× average).
+
+---
+
+**Generated**: 2025-11-27T18:27:08+0800  
+**Baseline**: Ox