taurus 0.1.0

data/docs/FUTURE_VISION.md

@@ -0,0 +1,303 @@
+# Future Vision: Taurus Beyond v0.4.0
+
+**Created**: 2025-01-29
+**Status**: Planning Document
+**Context**: Long-term vision from TODO.libtaurus.md
+
+## Overview
+
+This document captures the long-term architectural vision for Taurus, including transformation into libtaurus (a reusable C library) and enhanced features. This represents work beyond v0.4.0 and likely v0.5.0+.
+
+## Vision: libtaurus - Reusable C Library
+
+### Goal
+
+Refactor Taurus into **libtaurus**, a standalone C library that can be:
+- Linked into other C/C++ projects
+- Used by the Taurus CLI (written in C)
+- Wrapped by the Ruby gem (taurus)
+- Integrated into any language with C FFI
+
+### Architecture
+
+```
+┌─────────────────────────────────────────┐
+│         Language Bindings               │
+│  ┌──────────┐  ┌──────────┐  ┌────────┐│
+│  │  Ruby    │  │  Python  │  │  Node  ││
+│  │  Gem     │  │  Package │  │  Module││
+│  └──────────┘  └──────────┘  └────────┘│
+└─────────────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│          libtaurus.so                   │
+│     (Core  C Library + API)              │
+│  ┌─────────────────────────────────────┐│
+│  │ XML Parser (SAX/StAX/DOM)           ││
+│  │ XPath 1.0 Engine                    ││
+│  │ XML Namespaces 1.0                  ││
+│  │ Pretty Printing                     ││
+│  │ Memory Management                   ││
+│  └─────────────────────────────────────┘│
+└─────────────────────────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│          CLI Applications               │
+│  ┌──────────┐  ┌──────────┐            │
+│  │  taurus  │  │  Custom  │            │
+│  │  CLI     │  │  Tools   │            │
+│  └──────────┘  └──────────┘            │
+└─────────────────────────────────────────┘
+```
+
+### Components
+
+#### 1. libtaurus (Core C Library)
+- **Pure C implementation** with clean API
+- **Zero dependencies** (no libxml2)
+- **Thread-safe** operations
+- **Memory efficient** with configurable allocators
+- **Cross-platform** (Linux, macOS, Windows, BSD)
+- **CMake build system**
+
+**Features**:
+- XML parsing (SAX, StAX, DOM modes)
+- XPath 1.0 evaluation
+- XML Namespaces 1.0
+- XML pretty-printing
+- Error handling with detailed messages
+- Memory management with custom allocators
+
+**API Design**:
+```c
+// Core parsing
+taurus_document_t* taurus_parse_string(const char* xml, size_t len, taurus_options_t* opts);
+taurus_document_t* taurus_parse_file(const char* filename, taurus_options_t* opts);
+
+// XPath evaluation
+taurus_nodeset_t* taurus_xpath_eval(taurus_document_t* doc, const char* expr);
+
+// Pretty printing
+char* taurus_format_xml(taurus_document_t* doc, taurus_format_options_t* opts);
+
+// Memory management
+void taurus_document_free(taurus_document_t* doc);
+void taurus_nodeset_free(taurus_nodeset_t* nodeset);
+```
+
+#### 2. Taurus CLI (C Application)
+- **Standalone binary** linking libtaurus
+- **xmllint-compatible** commands and options
+- **Fast startup** (C binary, no Ruby overhead)
+- **Shell-friendly** with proper exit codes
+
+**Commands** (inspired by xmllint):
+```bash
+# XPath queries
+taurus --xpath "//book[@price > 20]" document.xml
+
+# Pretty printing
+taurus --format --indent 2 document.xml
+taurus --format --compact document.xml
+
+# Validation
+taurus --validate document.xml
+
+# Schema validation (future)
+taurus --schema schema.xsd document.xml
+
+# Debugging
+taurus --debug --xpath "//item" document.xml
+taurus --timing document.xml
+```
+
+#### 3. Ruby Gem (High-Level Interface)
+- **Thin wrapper** around libtaurus
+- **Ruby-friendly** API with blocks and iterators
+- **Current API preserved** for backward
+
+ compatibility
+- **Performance** close to direct C usage
+
+**Implementation**:
+```ruby
+# Current approach (stays the same externally)
+doc = Taurus.parse(xml)
+results = doc.xpath('//book')
+
+# Internally backed by libtaurus C library
+```
+
+### Parsing Modes
+
+#### SAX (Event-Driven)
+- **Memory efficient**: Stream processing
+- **Fast**: No DOM construction
+- **Use case**: Large documents, extraction
+
+```c
+taurus_sax_parse(xml, &callbacks, user_data);
+```
+
+#### StAX (Pull Parsing)
+- **Control**: Application pulls events
+- **Flexible**: Skip unwanted sections
+- **Use case**: Selective parsing
+
+```c
+taurus_reader_t* reader = taurus_reader_new(xml);
+while (taurus_reader_read(reader)) {
+    // Process events
+}
+```
+
+#### DOM (Tree Construction)
+- **Convenient**: Full tree in memory
+- **XPath**: Enables complex queries
+- **Use case**: Current Taurus behavior
+
+```c
+taurus_document_t* doc = taurus_parse_string(xml, len, NULL);
+```
+
+### XML Pretty Printing
+
+**Features**:
+- Configurable indentation (spaces/tabs)
+- Line wrapping at specified column
+- Attribute formatting (inline/separate lines)
+- Whitespace normalization
+- Compact mode (remove all whitespace)
+
+**Options**:
+```c
+typedef struct {
+    int indent_size;        // 2, 4, etc.
+    bool use_tabs;          // tabs vs spaces
+    int wrap_column;        // 80, 120, etc.
+    bool compact;           // remove whitespace
+    bool sort_attributes;   // alphabetical
+} taurus_format_options_t;
+```
+
+## Implementation Roadmap
+
+### Phase 1: API Stabilization (v0.4.0-v0.5.0)
+- Complete current Ruby API
+- Ensure comprehensive test coverage
+- Document all behaviors
+- Establish API contracts
+
+### Phase 2: C API Design (v0.6.0)
+- Design libtaurus C API
+- Create header files
+- Document API conventions
+- Plan memory management
+
+### Phase 3: Refactoring (v0.7.0)
+- Extract C code into libtaurus
+- Maintain Ruby bindings
+- Separate concerns cleanly
+- Add C unit tests
+
+### Phase 4: Multi-Mode Parsing (v0.8.0)
+- Implement SAX parsing
+- Implement StAX parsing
+- Keep DOM mode (current)
+- Add mode selection API
+
+### Phase 5: CLI Implementation (v0.9.0)
+- Build C CLI using libtaurus
+- Implement xmllint-compatible commands
+- Add taurus-specific features
+- Document CLI usage
+
+### Phase 6: Pretty Printing (v0.9.0)
+- Implement formatting engine
+- Add configuration options
+- Support various styles
+- Integrate with CLI
+
+### Phase 7: CMake Build (v0.10.0)
+- Create CMake build system
+- Support cross-compilation
+- Generate pkg-config files
+- Build shared/static libraries
+
+### Phase 8: Language Bindings (v1.0.0+)
+- Python bindings
+- Node.js bindings
+- Other language bindings
+- Consistent API across languages
+
+## Technical Considerations
+
+### Memory Management
+- **Allocator API**: Allow custom allocators
+- **Reference Counting**: For shared resources
+- **Pool Allocators**: For high-frequency allocations
+- **Leak Detection**: Built-in debugging support
+
+### Thread Safety
+- **Immutable Documents**: Safe to share
+- **Context Isolation**: Per-thread contexts
+- **Lock-Free Reads**: Where possible
+- **Documented Guarantees**: Clear thread-safety docs
+
+### Error Handling
+- **Error Codes**: Standard C approach
+- **Error Context**: Detailed error information
+- **Recovery**: Graceful error handling
+- **Logging**: Configurable logging levels
+
+### Performance
+- **Zero-Copy**: Where possible
+- **SIMD**: Continue optimizations
+- **Memory Pools**: Reduce allocations
+- **Lazy Evaluation**: Defer expensive operations
+
+## Benefits
+
+### For C/C++ Projects
+- **Direct Integration**: No Ruby dependency
+- **Fast Performance**: Native C speed
+- **Small Footprint**: Minimal binary size
+- **Standard API**: Familiar C patterns
+
+### For Other Languages
+- **Easy Bindings**: Standard C FFI
+- **Consistent Behavior**: Same core library
+- **Native Performance**: No interpretation overhead
+- **Wide Compatibility**: Works everywhere
+
+### For Taurus Users
+- **Faster CLI**: C binary startup
+- **More Modes**: SAX/StAX options
+- **Better Tools**: Enhanced CLI features
+- **Same API**: Backward compatible
+
+## Migration Path
+
+1. **v0.4.0**: Complete documentation
+2. **v0.5.0**: Namespace prefixes, API finalization
+3. **v0.6.0**: Design and prototype libtaurus API
+4. **v0.7.0**: Refactor to libtaurus + Ruby bindings
+5. **v0.8.0**: Add SAX/StAX modes
+6. **v0.9.0**: C CLI + pretty printing
+7. **v1.0.0**: Stable libtaurus release
+
+## Timeline
+
+- **Near-term (2025)**: v0.4.0-v0.5.0 (Ruby focus)
+- **Mid-term (2026)**: v0.6.0-v0.8.0 (libtaurus extraction)
+- **Long-term (2027+)**: v0.9.0-v1.0.0 (Multi-language, stable)
+
+## Conclusion
+
+This vision transforms Taurus from a Ruby gem into a universal XML processing library usable from any language. The core libtaurus library would provide fast, reliable XML processing while maintaining backward compatibility with the current Ruby API.
+
+**Key Principle**: Evolution, not revolution. Each step maintains compatibility while adding new capabilities.
+
+**Next Review**: After v0.5.0 completion (2025 Q2)

data/docs/GITHUB_ACTIONS.md

@@ -0,0 +1,293 @@
+# GitHub Actions CI/CD Setup
+
+## Overview
+
+Taurus uses GitHub Actions for continuous integration, testing, and automated releases across multiple platforms and Ruby versions.
+
+## Workflows
+
+### 1. CI/CD Workflow (`.github/workflows/main.yml`)
+
+**Triggers:**
+- Push to `main` branch
+- Pull requests
+- Manual dispatch
+
+**Features:**
+- Multi-platform testing (Ubuntu x64/ARM64, macOS Intel/Apple Silicon)
+- Multiple Ruby versions (3.0, 3.1, 3.2, 3.3, 3.4)
+- Matrix-based configuration from `matrix.json`
+- C extension compilation
+- Ruby (RSpec) and C (Google Test) unit tests
+- Performance benchmarks
+- RuboCop linting
+- Artifact collection
+
+**Jobs:**
+1. `load-matrix` - Loads platform/Ruby combinations from matrix.json
+2. `test` - Runs full test suite on all matrix configurations
+3. `benchmark` - Performance benchmarks on Ubuntu and macOS
+4. `lint` - Code quality checks with RuboCop
+5. `all-checks` - Verifies all tests passed
+
+### 2. Release Workflow (`.github/workflows/release.yml`)
+
+**Triggers:**
+- Push of version tags (`v*`)
+- Manual dispatch with version input
+
+**Features:**
+- Cross-platform native gem building
+- Automated GitHub releases
+- RubyGems.org publication
+- Installation verification
+
+**Jobs:**
+1. `build-native-gems` - Builds native gems for:
+   - x86_64-linux (Ubuntu 20.04+)
+   - x86_64-darwin (Intel Macs)
+   - arm64-darwin (Apple Silicon)
+
+2. `build-source-gem` - Builds source gem for other platforms
+
+3. `create-release` - Creates GitHub release with:
+   - All gem files
+   - SHA256 checksums
+   - Release notes
+
+4. `publish-rubygems` - Publishes to RubyGems.org
+
+5. `verify-release` - Tests installation from RubyGems on multiple platforms
+
+## Matrix Configuration
+
+The `matrix.json` file defines all platform/Ruby combinations for testing:
+
+```json
+[
+  {
+    "runner": "ubuntu-22.04",
+    "os": "ubuntu",
+    "arch": "x64",
+    "ruby": "3.3",
+    "name": "ubuntu-22-ruby-3.3"
+  },
+  ...
+]
+```
+
+**Supported Platforms:**
+- Ubuntu 22.04 (x64, ARM64)
+- macOS 13 (Intel)
+- macOS latest (Apple Silicon)
+
+**Ruby Versions:**
+- 3.0, 3.1, 3.2, 3.3, 3.4
+
+## Setup Requirements
+
+### For CI/CD
+
+No additional setup required - workflows run automatically on push/PR.
+
+### For Releases
+
+Required GitHub secrets:
+- `RUBYGEMS_API_KEY` - API key for publishing to RubyGems.org
+
+**To set up:**
+1. Get API key from https://rubygems.org/profile/edit
+2. Go to repository Settings → Secrets and variables → Actions
+3. Add new secret named `RUBYGEMS_API_KEY`
+
+## Creating a Release
+
+### Automatic (Recommended)
+
+1. Update version in `lib/taurus/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit changes: `git commit -m "chore: bump version to X.Y.Z"`
+4. Create and push tag:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+5. GitHub Actions automatically:
+   - Builds native gems
+   - Creates GitHub release
+   - Publishes to RubyGems
+   - Verifies installation
+
+### Manual Dispatch
+
+1. Go to Actions → Release workflow
+2. Click "Run workflow"
+3. Enter version (e.g., `0.1.0`)
+4. Click "Run workflow"
+
+## Artifacts
+
+### Test Artifacts
+
+Each test run produces:
+- Compiled native extensions (`.so`/`.bundle` files)
+- SHA256 checksums
+- Retention: 30 days
+
+### Release Artifacts
+
+Each release includes:
+- Source gem (all platforms)
+- Native gems (Linux x64, macOS x64, macOS ARM64)
+- Combined SHA256 checksums
+- Retention: Permanent (GitHub release)
+
+## Monitoring
+
+### Build Status
+
+Check build status:
+- Badge on README.md
+- Actions tab in GitHub repository
+- Email notifications (if configured)
+
+### Performance Tracking
+
+Benchmark artifacts available for:
+- Ubuntu latest
+- macOS latest
+
+Download from Actions → Workflow run → Artifacts
+
+## Troubleshooting
+
+### Build Failures
+
+**C Extension Won't Compile:**
+```bash
+# Local reproduction:
+bundle exec rake clean
+bundle exec rake compile
+```
+
+**Test Failures:**
+```bash
+# Run tests locally:
+bundle exec rake spec  # Ruby tests
+bundle exec rake test_c  # C tests
+```
+
+**Cross-compilation Issues:**
+- Check rake-compiler-dock is latest version
+- Verify extconf.rb lists all source files
+- Check for platform-specific #ifdef code
+
+### Release Failures
+
+**Native Gem Build Fails:**
+- Check rake-compiler-dock logs
+- Verify source files compile on target platform
+- Test locally with Docker:
+  ```bash
+  bundle exec rake-compiler-dock bash
+  ```
+
+**RubyGems Publication Fails:**
+- Verify `RUBYGEMS_API_KEY` secret is set
+- Check gem name isn't already taken
+- Ensure version number is unique
+
+**Verification Fails:**
+- Wait longer (gem indexing lag)
+- Check if gem published successfully
+- Verify gem installs manually:
+  ```bash
+  gem install taurus -v X.Y.Z
+  ```
+
+## Best Practices
+
+### Before Merging PRs
+
+- Ensure all tests pass
+- Check benchmark results for regressions
+- Review RuboCop warnings
+- Test on multiple platforms if changing C code
+
+### Before Releasing
+
+1. Run full test suite locally
+2. Update CHANGELOG.md
+3. Bump version number
+4. Test installation from local gem:
+   ```bash
+   gem build taurus.gemspec
+   gem install taurus-X.Y.Z.gem
+   ```
+5. Create tag and push
+
+### Maintaining Matrix
+
+When adding platforms:
+1. Add to `matrix.json`
+2. Test locally if possible
+3. Monitor first CI run
+4. Update documentation
+
+When deprecating Ruby:
+1. Remove from `matrix.json`
+2. Update README.md
+3. Update gemspec `required_ruby_version`
+
+## Performance Considerations
+
+### CI Speed
+
+Average runtime:
+- Test job: 5-10 minutes per platform
+- Benchmark: 10-15 minutes per platform
+- Total (parallel): ~15-20 minutes
+
+### Release Speed
+
+Average runtime:
+- Build gems: ~10 minutes (parallel)
+- Create release: ~2 minutes
+- Publish: ~5 minutes
+- Verify: ~10 minutes
+- Total: ~30 minutes
+
+## Future Enhancements
+
+### Planned
+
+- Windows support (MSYS2/MinGW)
+- Additional ARM64 platforms
+- Performance trend tracking
+- Code coverage reporting
+- Security scanning (Dependabot, CodeQL)
+
+### Under Consideration
+
+- Nightly builds with latest Ruby
+- Cross-Ruby compatibility matrix
+- Memory profiling in CI
+- Benchmark comparison vs. Nokogiri/Ox
+
+## Resources
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [ruby/setup-ruby Action](https://github.com/ruby/setup-ruby)
+- [rake-compiler Documentation](https://github.com/rake-compiler/rake-compiler)
+- [RubyGems API Documentation](https://guides.rubygems.org/rubygems-org-api/)
+
+## Support
+
+For CI/CD issues:
+1. Check Actions logs
+2. Search existing GitHub issues
+3. Create new issue with:
+   - Workflow run URL
+   - Platform/Ruby version
+   - Error messages
+   - Steps to reproduce