map 6.6.0 → 8.0.0

data/specs/001-ordered-map-module/quickstart.md

@@ -0,0 +1,430 @@
+# Developer Quickstart: Conditional Ordered Map Module
+
+**Feature**: Conditional Ordered Map Module
+**Branch**: `001-ordered-map-module`
+**Last Updated**: 2025-11-10
+
+## Overview
+
+This guide helps developers understand and work with the conditional ordering module architecture in map.rb.
+
+## What Changed?
+
+### Before (All Ruby Versions)
+
+```ruby
+# lib/map.rb
+class Map < Hash
+  def keys
+    @keys ||= []  # Always maintained for ordering
+  end
+
+  def []=(key, val)
+    key, val = convert(key, val)
+    keys.push(key) unless has_key?(key)  # Always track
+    __set__(key, val)
+  end
+
+  # ... 10 other methods using @keys ...
+end
+```
+
+**Problem**: Ruby 1.9+ already maintains Hash ordering, so `@keys` is redundant (memory waste).
+
+### After (Version-Aware)
+
+```ruby
+# lib/map.rb
+class Map < Hash
+  # Core methods work for Ruby 1.9+ (no @keys needed)
+
+  # Conditionally include ordering module for legacy Ruby
+  if RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING']
+    require_relative 'map/ordering'
+    include Map::Ordering
+  end
+end
+
+# lib/map/ordering.rb
+module Map::Ordering
+  def self.included(base)
+    base.class_eval do
+      def self.allocate
+        super.instance_eval do
+          @keys = []
+          self
+        end
+      end
+    end
+  end
+
+  def keys
+    @keys ||= []
+  end
+
+  def []=(key, val)
+    key, val = convert(key, val)
+    keys.push(key) unless has_key?(key)
+    __set__(key, val)
+  end
+
+  # ... other ordering methods ...
+end
+```
+
+**Solution**: Ruby 1.9+ uses native Hash ordering, Ruby < 1.9 includes module for manual ordering.
+
+## Architecture
+
+### Component Diagram
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Map Class                        │
+│                  (extends Hash)                     │
+│                                                     │
+│  Core methods (work on Ruby 1.9+ with native Hash)│
+│  - convert_key, convert_value                      │
+│  - initialize, update, merge                       │
+│  - get, set (use Hash methods)                     │
+└─────────────────────────────────────────────────────┘
+                        △
+                        │
+                        │ conditionally includes
+                        │ (if RUBY_VERSION < '1.9')
+                        │
+┌─────────────────────────────────────────────────────┐
+│              Map::Ordering Module                   │
+│                                                     │
+│  Ordering-specific methods (override Hash methods):│
+│  - allocate (class method via included hook)       │
+│  - keys, values, first, last                       │
+│  - each, each_key, each_value, each_with_index     │
+│  - []=, delete                                     │
+│                                                     │
+│  Uses @keys array to maintain insertion order      │
+└─────────────────────────────────────────────────────┘
+```
+
+### Decision Tree
+
+```
+Map class loaded
+    │
+    ├─ Is RUBY_VERSION < '1.9'?
+    │   ├─ YES → Include Map::Ordering
+    │   │         └─ Use @keys array for ordering
+    │   └─ NO ──┐
+    │           │
+    └─ Is ENV['MAP_FORCE_ORDERING'] set?
+        ├─ YES → Include Map::Ordering (testing mode)
+        │         └─ Use @keys array for ordering
+        └─ NO → No module inclusion
+                 └─ Use native Hash ordering
+```
+
+## Development Workflow
+
+### Setting Up Your Environment
+
+```bash
+# Clone and checkout feature branch
+git clone https://github.com/ahoward/map.git
+cd map
+git checkout 001-ordered-map-module
+
+# Check Ruby version
+ruby --version
+# Should be 3.0+ per current gemspec
+```
+
+### Running Tests
+
+#### Normal Mode (Ruby 1.9+ behavior)
+
+```bash
+# Run all tests using native Hash ordering
+rake test
+```
+
+Expected:
+- All tests pass
+- Map instances have NO `@keys` instance variable
+- Ordering works via Hash#keys, Hash#each, etc.
+
+#### Forced Ordering Mode (Ruby < 1.9 simulation)
+
+```bash
+# Force inclusion of ordering module
+MAP_FORCE_ORDERING=1 rake test
+```
+
+Expected:
+- All tests pass
+- Map instances HAVE `@keys` instance variable
+- Ordering works via `@keys` array tracking
+
+### Verifying Both Paths
+
+```ruby
+# Quick verification script
+# test/verify_ordering.rb
+
+require 'map'
+
+def test_ordering_module_state
+  map = Map[:a, 1, :b, 2, :c, 3]
+
+  puts "Ruby Version: #{RUBY_VERSION}"
+  puts "Force Ordering: #{ENV['MAP_FORCE_ORDERING']}"
+  puts "Has @keys: #{map.instance_variables.include?(:@keys)}"
+  puts "Keys: #{map.keys.inspect}"
+  puts "Values: #{map.values.inspect}"
+  puts "First: #{map.first.inspect}"
+  puts "Last: #{map.last.inspect}"
+
+  # Verify ordering is maintained
+  raise "Ordering broken!" unless map.keys == ['a', 'b', 'c']
+  raise "Values broken!" unless map.values == [1, 2, 3]
+
+  puts "✅ All checks passed!"
+end
+
+test_ordering_module_state
+```
+
+Run both ways:
+
+```bash
+# Test without ordering module
+ruby test/verify_ordering.rb
+# Should show: Has @keys: false
+
+# Test with ordering module
+MAP_FORCE_ORDERING=1 ruby test/verify_ordering.rb
+# Should show: Has @keys: true
+```
+
+## Code Organization
+
+### File Structure
+
+```
+lib/map.rb                  # Main Map class
+                            # - Contains conditional include logic
+                            # - Methods work for Ruby 1.9+ native ordering
+
+lib/map/ordering.rb         # NEW: Ordering module
+                            # - All @keys-dependent methods
+                            # - Included only when needed
+
+lib/map/_lib.rb            # Unchanged: utility methods
+lib/map/options.rb         # Unchanged: Map::Options subclass
+```
+
+### What Goes Where?
+
+**lib/map.rb** (Methods that work with native Hash ordering):
+- `convert_key` - Key normalization (string/symbol)
+- `convert_value` - Recursive Map conversion
+- `initialize`, `update`, `merge` - Constructors and merging
+- `get` (fetch with nested paths) - Doesn't depend on ordering
+- `method_missing` - Attribute-style access
+
+**lib/map/ordering.rb** (Methods that need `@keys` array):
+- `allocate` - Initialize `@keys = []`
+- `keys` - Return `@keys`
+- `values` - Iterate `@keys` to build values array
+- `[]=`, `delete` - Track keys in `@keys`
+- `each`, `each_key`, `each_value`, `each_with_index` - Iterate via `@keys`
+- `first`, `last` - Use `@keys.first`, `@keys.last`
+
+## Common Development Tasks
+
+### Adding a New Method to Map
+
+**Question**: Should it go in `Map` or `Map::Ordering`?
+
+**Decision tree**:
+1. Does it depend on key ordering?
+   - NO → Add to `lib/map.rb`
+   - YES → Continue to #2
+2. Does it need `@keys` array specifically?
+   - NO → Add to `lib/map.rb` (can use Hash methods)
+   - YES → Add to `lib/map/ordering.rb`
+
+**Examples**:
+
+```ruby
+# Example 1: New method that doesn't care about ordering
+# Add to lib/map.rb
+def has_nested?(path)
+  get(path) != nil
+end
+
+# Example 2: New method that needs ordering but can use Hash methods
+# Add to lib/map.rb (works on Ruby 1.9+)
+def second
+  key = keys[1]  # Hash#keys is ordered on 1.9+
+  [key, self[key]]
+end
+
+# Example 3: New method that explicitly needs @keys
+# Add to lib/map/ordering.rb
+def reverse_each
+  @keys.reverse.each { |key| yield(key, self[key]) }
+end
+```
+
+### Modifying an Ordering Method
+
+If you need to modify a method in `Map::Ordering`:
+
+1. Edit `lib/map/ordering.rb`
+2. Test both paths:
+   ```bash
+   # Ruby 1.9+ path (should still work without your change)
+   rake test
+
+   # Legacy path (should work with your change)
+   MAP_FORCE_ORDERING=1 rake test
+   ```
+
+### Debugging Ordering Issues
+
+```ruby
+# Add to your test or debugging session
+map = Map[:a, 1, :b, 2]
+
+# Check which path is being used
+if map.instance_variables.include?(:@keys)
+  puts "Using Map::Ordering module"
+  puts "@keys = #{map.instance_variable_get(:@keys).inspect}"
+else
+  puts "Using native Hash ordering"
+end
+
+# Verify ordering consistency
+puts "Keys order: #{map.keys.inspect}"
+puts "Each order: #{map.map { |k, v| k }.inspect}"
+```
+
+## Testing Strategy
+
+### Test Categories
+
+1. **Functional tests** (existing in `test/map_test.rb`):
+   - No modifications needed
+   - Run in both modes to verify identical behavior
+
+2. **Internal state tests** (NEW tests to add):
+   - Verify `@keys` presence/absence based on mode
+   - Check memory footprint differences
+   - Validate synchronization on Ruby < 1.9 mode
+
+3. **Performance benchmarks** (optional):
+   - Compare iteration speed with/without module
+   - Measure memory usage with/without `@keys`
+
+### Writing New Tests
+
+```ruby
+# In test/map_test.rb
+
+Testing Map do
+  testing 'conditional ordering module inclusion' do
+    map = Map[:a, 1, :b, 2, :c, 3]
+
+    # Test behavior (should work in both modes)
+    assert{ map.keys == ['a', 'b', 'c'] }
+    assert{ map.values == [1, 2, 3] }
+
+    # Test internal state (mode-dependent)
+    if ENV['MAP_FORCE_ORDERING'] || RUBY_VERSION < '1.9'
+      assert{ map.instance_variables.include?(:@keys) }
+    else
+      assert{ !map.instance_variables.include?(:@keys) }
+    end
+  end
+end
+```
+
+## Troubleshooting
+
+### Problem: Tests pass normally but fail with MAP_FORCE_ORDERING=1
+
+**Cause**: Likely a method is missing from `Map::Ordering` module
+
+**Solution**:
+1. Identify which test is failing
+2. Check if the failing method uses `@keys`
+3. Add missing method to `lib/map/ordering.rb`
+
+### Problem: Memory usage isn't reduced on Ruby 3.x
+
+**Cause**: Module is being included when it shouldn't be
+
+**Solution**:
+```ruby
+# Verify module isn't included
+map = Map.new
+puts map.instance_variables.inspect
+# Should be: [] (empty, no @keys)
+
+# Check if module was mistakenly included
+puts Map.ancestors.include?(Map::Ordering)
+# Should be: false (on Ruby 1.9+)
+```
+
+### Problem: Subclass behavior differs from Map
+
+**Cause**: Ordering module methods not inherited properly
+
+**Solution**:
+```ruby
+# Verify inheritance chain
+puts Map::Options.ancestors
+# Should include Map::Ordering if Map does
+
+# Test with subclass
+opts = Map::Options[:a, 1, :b, 2]
+puts opts.keys.inspect
+# Should be: ['a', 'b'] (ordered)
+```
+
+## Performance Considerations
+
+### Memory Impact
+
+| Scenario | Before | After | Savings |
+|----------|--------|-------|---------|
+| Ruby 1.8.x | `@keys` array | `@keys` array | 0% (unchanged) |
+| Ruby 1.9-2.x | `@keys` array | No `@keys` | ~25% per instance |
+| Ruby 3.x | `@keys` array | No `@keys` | ~25% per instance |
+
+### CPU Impact
+
+| Operation | Ruby < 1.9 (with module) | Ruby >= 1.9 (native) | Impact |
+|-----------|-------------------------|----------------------|---------|
+| Insert | Track in `@keys` + Hash | Hash only | Negligible (one less array operation) |
+| Iterate | Iterate `@keys` array | Iterate Hash | Negligible (both O(n)) |
+| Delete | Remove from `@keys` + Hash | Hash only | Minor (array search removed) |
+
+**Expected**: No measurable performance difference (< 5% regression per success criteria).
+
+## Next Steps
+
+After reviewing this quickstart:
+
+1. Read the [data-model.md](data-model.md) for detailed state diagrams
+2. Review [research.md](research.md) for technical decisions
+3. Proceed to implementation using the `/speckit.tasks` command to generate implementation tasks
+
+## Questions?
+
+If you encounter issues or have questions:
+
+1. Check the [data-model.md](data-model.md) for state model details
+2. Review [research.md](research.md) for decision rationale
+3. Examine existing tests in `test/map_test.rb` for examples
+4. Run verification script to diagnose which path is active

data/specs/001-ordered-map-module/research.md

@@ -0,0 +1,189 @@
+# Research: Conditional Ordered Map Module
+
+**Date**: 2025-11-10
+**Feature**: Conditional Ordered Map Module
+**Phase**: 0 - Research & Technical Decisions
+
+## Overview
+
+This document captures research findings and technical decisions for extracting ordering-related code into a conditional module for the map.rb library.
+
+## Key Research Areas
+
+### 1. Ruby Hash Ordering History
+
+**Decision**: Use Ruby version 1.9.0 as the cutoff for conditional module inclusion
+
+**Rationale**:
+- Ruby 1.8.x: Hash was **unordered** - iteration order was unpredictable and based on internal hash table structure
+- Ruby 1.9.0+: Hash became **ordered by insertion** - maintains the order in which keys were added
+- This change was formalized in Ruby 1.9 and has been maintained in all subsequent versions (2.x, 3.x)
+- The change applies to all major Ruby implementations (MRI, JRuby, Rubinius, TruffleRuby) at their respective 1.9+ version equivalents
+
+**Alternatives considered**:
+- Using RUBY_VERSION string comparison: Rejected due to complexity with alternative Ruby implementations
+- Using feature detection (checking if Hash preserves order): Rejected as overly complex for a well-known version boundary
+- Using Ruby 2.0 as cutoff: Rejected as 1.9.x still had significant usage when map.rb was established
+
+**References**:
+- Ruby 1.9 release notes documented the Hash ordering change
+- This is a well-established Ruby language feature with no ambiguity across implementations
+
+### 2. Module Inclusion Strategy
+
+**Decision**: Use conditional `include` at class definition time based on RUBY_VERSION constant
+
+**Rationale**:
+- Simple, explicit, and evaluated once at load time (zero runtime overhead)
+- Ruby's RUBY_VERSION constant is available in all Ruby versions
+- Module inclusion allows clean separation of ordering-specific methods
+- Methods in the module override Hash superclass methods when included
+
+**Implementation approach**:
+```ruby
+class Map < Hash
+  # ... existing code ...
+
+  # Conditionally include ordering module for Ruby < 1.9
+  if RUBY_VERSION < '1.9'
+    require_relative 'map/ordering'
+    include Map::Ordering
+  end
+end
+```
+
+**Alternatives considered**:
+- Runtime method checks: Rejected due to performance overhead on every method call
+- Monkey-patching after class definition: Rejected as less maintainable and harder to test
+- Separate Map class for each version: Rejected as it duplicates code and breaks the "single class" design
+
+### 3. Methods to Extract into Ordering Module
+
+**Decision**: Extract all methods that directly depend on the `@keys` instance variable
+
+**Methods identified from lib/map.rb analysis**:
+1. `Map.allocate` - Initializes `@keys = []`
+2. `keys` - Returns `@keys` array
+3. `[]=` (store) - Tracks key in `@keys.push(key)` on new insertions
+4. `values` - Iterates over `@keys` to build values array
+5. `first` - Returns `[keys.first, self[keys.first]]`
+6. `last` - Returns `[keys.last, self[keys.last]]`
+7. `each` (and `each_pair`) - Iterates over `@keys` array
+8. `each_key` - Iterates over `@keys` array
+9. `each_value` - Iterates over `@keys` to access values
+10. `each_with_index` - Iterates over `@keys.each_with_index`
+11. `delete` - Removes key from `@keys` array
+
+**Rationale**:
+- These methods explicitly use `@keys` for ordering guarantees
+- In Ruby 1.9+, Hash superclass provides ordered versions of these methods
+- Extracting to module allows clean fallback to Hash methods when module not included
+
+**Alternatives considered**:
+- Extracting only iterator methods: Rejected as incomplete - would still need `@keys` for `first`/`last`
+- Keeping `@keys` for backward compatibility: Rejected as it defeats the memory optimization goal
+
+### 4. Testing Strategy (KISS Approach)
+
+**Decision**: Use environment variable `MAP_FORCE_ORDERING=1` to force inclusion of ordering module regardless of Ruby version
+
+**Rationale**:
+- Simple: Single environment variable toggle
+- KISS: No complex test matrix infrastructure needed
+- Effective: Allows testing both code paths on any Ruby version
+- Non-invasive: Doesn't require test suite modifications
+
+**Implementation**:
+```ruby
+# In lib/map.rb
+if RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING']
+  require_relative 'map/ordering'
+  include Map::Ordering
+end
+```
+
+**Test execution**:
+```bash
+# Test normal path (Ruby 1.9+ without ordering module)
+rake test
+
+# Test ordering module path (forced inclusion)
+MAP_FORCE_ORDERING=1 rake test
+```
+
+**Alternatives considered**:
+- Separate test files for each path: Rejected as it duplicates test code
+- Docker containers with multiple Ruby versions: Rejected as over-engineered for this simple need
+- Rake tasks that modify source before testing: Rejected as fragile and error-prone
+- RSpec shared examples: Rejected as map.rb uses custom testing framework, not RSpec
+
+### 5. Marshal Compatibility Considerations
+
+**Decision**: Accept potential Marshal incompatibility across Ruby versions as documented limitation
+
+**Rationale**:
+- Maps created on Ruby 1.8.x will have `@keys` instance variable
+- Maps created on Ruby 1.9+ will NOT have `@keys` instance variable
+- Marshal.load of cross-version dumps may produce Maps with inconsistent internal state
+- This is acceptable because:
+  - Marshal is typically used within same runtime environment
+  - Cross-version Marshal compatibility is rarely needed in practice
+  - Users can work around by converting to Hash, then back to Map if needed
+
+**Mitigation**:
+- Document this limitation in CHANGELOG and upgrade notes
+- Provide helper method to normalize Maps if cross-version Marshal support is needed
+
+**Alternatives considered**:
+- Custom marshal_dump/marshal_load: Rejected as it adds complexity for an edge case
+- Always including @keys for Marshal compatibility: Rejected as it defeats the optimization
+- Raising error on cross-version load: Rejected as too defensive
+
+### 6. Alternative Ruby Implementation Compatibility
+
+**Decision**: Trust that alternative implementations (JRuby, Rubinius, TruffleRuby) follow MRI Hash ordering behavior at their version boundaries
+
+**Rationale**:
+- JRuby 1.9+ mode guarantees Hash ordering (matches MRI 1.9 behavior)
+- Rubinius follows MRI compatibility at version equivalents
+- TruffleRuby explicitly aims for MRI compatibility
+- RUBY_VERSION constant reflects the Ruby version being emulated
+
+**Risk assessment**: Low - Hash ordering is part of the Ruby spec since 1.9, all major implementations comply
+
+**Alternatives considered**:
+- Platform-specific detection: Rejected as unnecessary complexity
+- Feature-based detection (test if Hash preserves order): Rejected as over-engineered
+
+## Technical Decisions Summary
+
+| Decision Point | Choice | Rationale |
+|----------------|--------|-----------|
+| Version cutoff | Ruby 1.9.0 | Well-documented Hash ordering introduction |
+| Inclusion mechanism | Conditional `include` at load time | Zero runtime overhead, simple and clear |
+| Methods to extract | All `@keys`-dependent methods (11 methods) | Complete separation, enables Hash method delegation |
+| Testing approach | Environment variable `MAP_FORCE_ORDERING=1` | KISS principle, easy to use, no test modifications |
+| Marshal compatibility | Accept limitation, document workaround | Edge case doesn't justify complexity |
+| Alt Ruby impls | Trust RUBY_VERSION constant | All major implementations comply with spec |
+
+## Implementation Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|-----------|------------|
+| Ruby version detection fails on unknown implementation | High | Very Low | RUBY_VERSION is universal Ruby constant |
+| Tests fail on older Ruby due to syntax | High | Low | Use Ruby 1.8-compatible syntax in ordering module |
+| Performance regression on Ruby 1.9+ | Medium | Very Low | No code changes to 1.9+ path, only omission of module |
+| Subclasses of Map break | High | Low | Test with Map::Options subclass, verify inheritance |
+| Marshal incompatibility causes production issues | Medium | Very Low | Document limitation, provide conversion helper |
+
+## Next Steps (Phase 1)
+
+Based on research findings, Phase 1 will generate:
+
+1. **data-model.md**: Document the internal state model (with/without `@keys` based on Ruby version)
+2. **contracts/**: N/A for this feature (no external APIs, internal refactoring only)
+3. **quickstart.md**: Developer guide for working with the new module structure
+
+## Open Questions
+
+None - all research areas resolved with clear decisions.