map 6.6.0 → 8.0.0

data/specs/001-ordered-map-module/checklists/requirements.md

@@ -0,0 +1,62 @@
+# Specification Quality Checklist: Conditional Ordered Map Module
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-10
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Validation Notes
+
+### Passed Items
+
+**Content Quality**: All items passed
+- Spec focuses on WHAT and WHY, not HOW
+- Written in business/user language (backward compatibility, ordering behavior, testing)
+- No framework-specific or implementation details in requirements
+
+**Requirement Completeness**: All items passed
+- No [NEEDS CLARIFICATION] markers present
+- All 9 functional requirements are testable (can verify module extraction, conditional inclusion, version detection, API compatibility, etc.)
+- Success criteria include specific metrics (100% ordering operations correct, no @keys variable present, max 5% test time regression)
+- Success criteria are technology-agnostic (focus on outcomes like "memory footprint reduced" not "implement using X")
+- 3 user stories with clear acceptance scenarios covering legacy support, modern optimization, and testing
+- Edge cases identified (alternative Ruby implementations, Marshal compatibility, inheritance)
+- Scope clearly bounded by backward compatibility and API stability requirements
+- Assumptions document defaults (Ruby 1.9 cutoff, Marshal compatibility tradeoff, KISS testing approach)
+- Dependencies identified (Ruby version environments, test suite adequacy, no API breaking changes)
+
+**Feature Readiness**: All items passed
+- Each functional requirement maps to acceptance scenarios in user stories
+- User scenarios cover all three priority flows: P1 (legacy support), P2 (modern optimization), P3 (testing)
+- Success criteria define clear measurable outcomes (test pass rates, memory inspection, performance benchmarks)
+- Spec maintains clean separation - no leakage of module names, version detection mechanisms, or test implementation details into WHAT the system must do
+
+## Conclusion
+
+**Status**: ✅ READY FOR PLANNING
+
+All checklist items have passed validation. The specification is complete, unambiguous, and ready to proceed to `/speckit.clarify` (if needed) or `/speckit.plan`.

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

@@ -0,0 +1,250 @@
+# Data Model: Conditional Ordered Map Module
+
+**Date**: 2025-11-10
+**Feature**: Conditional Ordered Map Module
+**Phase**: 1 - Design
+
+## Overview
+
+This document describes the internal state model and behavior of the Map class under the conditional ordering module architecture.
+
+## Entity: Map Class
+
+### Description
+
+Map is a string/symbol-indifferent ordered hash that extends Ruby's Hash class. Its internal state varies based on Ruby version to optimize for native Hash ordering capabilities.
+
+### State Model
+
+Map has two distinct internal state configurations depending on the Ruby runtime:
+
+#### Configuration 1: Ruby < 1.9 (Legacy Ordering)
+
+**Includes**: `Map::Ordering` module
+
+**Instance Variables**:
+- `@keys` (Array): Maintains insertion order of keys as strings
+
+**Behavior**:
+- Keys are tracked in `@keys` array upon insertion
+- Iteration methods (`each`, `each_key`, `each_value`) use `@keys` for deterministic ordering
+- `first` and `last` methods rely on `@keys.first` and `@keys.last`
+- `delete` removes key from both Hash storage and `@keys` array
+- `values` returns array built by iterating `@keys`
+
+**State Transitions**:
+```
+[Empty Map]
+  |
+  | Map[:a, 1]  ->  @keys = ['a'], Hash = {'a' => 1}
+  |
+[Map with one entry]
+  |
+  | map[:b] = 2  ->  @keys = ['a', 'b'], Hash = {'a' => 1, 'b' => 2}
+  |
+[Map with two entries]
+  |
+  | map.delete(:a)  ->  @keys = ['b'], Hash = {'b' => 2}
+  |
+[Map with one entry]
+```
+
+#### Configuration 2: Ruby >= 1.9 (Native Ordering)
+
+**Includes**: No ordering module
+
+**Instance Variables**:
+- None (Map-specific) - relies on Hash superclass storage
+
+**Behavior**:
+- Hash superclass maintains insertion order natively
+- Iteration methods delegate to Hash superclass implementations
+- `first` and `last` use Hash#first and Hash#last (available in Ruby 1.9+)
+- `delete` uses Hash#delete (automatically maintains ordering)
+- `values` uses Hash#values (preserves ordering)
+
+**State Transitions**:
+```
+[Empty Map]
+  |
+  | Map[:a, 1]  ->  Hash = {'a' => 1} (ordered)
+  |
+[Map with one entry]
+  |
+  | map[:b] = 2  ->  Hash = {'a' => 1, 'b' => 2} (ordered)
+  |
+[Map with two entries]
+  |
+  | map.delete(:a)  ->  Hash = {'b' => 2} (ordered)
+  |
+[Map with one entry]
+```
+
+## Entity: Map::Ordering Module
+
+### Description
+
+Module containing all ordering-related methods that manually track insertion order using an `@keys` array. This module is only included in Map when Ruby < 1.9 or when forced via `ENV['MAP_FORCE_ORDERING']`.
+
+### Methods
+
+#### Class Methods
+
+- `allocate`: Overrides Map.allocate to initialize `@keys = []` on new instances
+
+#### Instance Methods
+
+- `keys`: Returns `@keys` array (overrides Hash#keys)
+- `[]=` (store): Tracks new keys in `@keys` array, delegates storage to Hash
+- `values`: Builds array by iterating `@keys`, fetching each value
+- `first`: Returns `[keys.first, self[keys.first]]`
+- `last`: Returns `[keys.last, self[keys.last]]`
+- `each` / `each_pair`: Iterates `@keys`, yielding `[key, self[key]]` pairs
+- `each_key`: Iterates `@keys`, yielding each key
+- `each_value`: Iterates `@keys`, yielding `self[key]` for each
+- `each_with_index`: Iterates `@keys.each_with_index`, yielding `[[key, self[key]], index]`
+- `delete`: Removes key from `@keys` array, then calls `super` to delete from Hash
+
+### Constraints
+
+- `@keys` must contain only string keys (symbol keys are converted to strings by Map#convert_key)
+- Order of `@keys` must match insertion order
+- No duplicate keys in `@keys` array
+- `@keys` and Hash storage must stay synchronized (every key in one must be in the other)
+
+## Version Detection Logic
+
+### Conditional Inclusion
+
+```ruby
+# Pseudo-code for lib/map.rb
+class Map < Hash
+  # ... existing Map code ...
+
+  # Conditional module inclusion at class definition time
+  if RUBY_VERSION < '1.9' || ENV['MAP_FORCE_ORDERING']
+    require_relative 'map/ordering'
+    include Map::Ordering
+  end
+end
+```
+
+### Detection Rules
+
+| Condition | Module Included? | Rationale |
+|-----------|-----------------|-----------|
+| RUBY_VERSION < '1.9' | Yes | Hash is unordered, need manual tracking |
+| RUBY_VERSION >= '1.9' | No | Hash is ordered natively |
+| ENV['MAP_FORCE_ORDERING'] = '1' | Yes | Testing mode - force ordering module |
+| ENV['MAP_FORCE_ORDERING'] unset | Per version | Normal operation |
+
+## API Compatibility Matrix
+
+All public API methods maintain identical behavior regardless of configuration:
+
+| Method | Ruby < 1.9 (with module) | Ruby >= 1.9 (without module) | Compatible? |
+|--------|-------------------------|------------------------------|-------------|
+| `keys` | Returns `@keys` | Returns Hash#keys (ordered) | ✅ Yes |
+| `values` | Iterates `@keys` to build array | Returns Hash#values (ordered) | ✅ Yes |
+| `each` | Iterates `@keys` | Uses Hash#each (ordered) | ✅ Yes |
+| `first` | `[keys.first, self[keys.first]]` | Hash#first | ✅ Yes |
+| `last` | `[keys.last, self[keys.last]]` | Hash#last | ✅ Yes |
+| `delete` | Removes from `@keys` + Hash | Hash#delete (maintains order) | ✅ Yes |
+| `[]=` | Tracks in `@keys` + Hash | Hash#[]= (maintains order) | ✅ Yes |
+
+## Invariants
+
+### Cross-Configuration Invariants
+
+These properties must hold true in BOTH configurations:
+
+1. **Insertion order preservation**: `map.keys` always returns keys in insertion order
+2. **String/symbol indifference**: `map[:a]` and `map['a']` access the same value
+3. **Deterministic iteration**: Multiple calls to `each` yield keys in same order
+4. **First/last consistency**: `map.first[0] == map.keys.first`
+5. **No nil default**: Map doesn't work with non-nil default values (existing constraint)
+
+### Configuration-Specific Invariants
+
+#### Ruby < 1.9 with Ordering Module:
+
+1. **Synchronization**: `@keys.size == Hash.size` always
+2. **Key membership**: Every key in `@keys` exists in Hash, and vice versa
+3. **No duplicates**: `@keys.uniq.size == @keys.size`
+
+#### Ruby >= 1.9 without Ordering Module:
+
+1. **No @keys variable**: `instance_variables` should not include `@keys`
+2. **Hash delegation**: Ordering methods delegate to Hash superclass
+
+## Memory Footprint Comparison
+
+### Ruby < 1.9 (with Ordering Module)
+
+Per Map instance:
+- Hash storage: ~40 bytes + (n * 24 bytes per entry)
+- `@keys` array: ~40 bytes + (n * 8 bytes per string reference)
+- **Total overhead**: ~80 bytes + (n * 32 bytes)
+
+### Ruby >= 1.9 (without Ordering Module)
+
+Per Map instance:
+- Hash storage: ~40 bytes + (n * 24 bytes per entry)
+- **Total overhead**: ~40 bytes + (n * 24 bytes)
+
+### Memory Savings
+
+For a Map with 100 entries:
+- Ruby < 1.9: ~3,280 bytes
+- Ruby >= 1.9: ~2,440 bytes
+- **Savings**: ~840 bytes (25% reduction)
+
+For a Map with 1,000 entries:
+- Ruby < 1.9: ~32,080 bytes
+- Ruby >= 1.9: ~24,040 bytes
+- **Savings**: ~8,040 bytes (25% reduction)
+
+## Subclassing Considerations
+
+### Map::Options
+
+The existing `Map::Options` subclass inherits ordering behavior from Map:
+
+- If Map includes `Map::Ordering`, Map::Options inherits those methods
+- If Map doesn't include `Map::Ordering`, Map::Options uses Hash ordering
+- No changes required to Map::Options implementation
+
+### Future Subclasses
+
+Any subclass of Map will:
+- Automatically get appropriate ordering behavior based on Ruby version
+- Inherit `@keys` initialization if Ordering module is included
+- Be able to override ordering methods if needed (standard Ruby inheritance)
+
+## Testing Verification Points
+
+To verify correct data model implementation:
+
+1. **Instance variable presence**: Check `instance_variables.include?(:@keys)` matches expected configuration
+2. **Ordering correctness**: Verify `keys`, `values`, `each` return deterministic order
+3. **Synchronization**: On Ruby < 1.9, verify `@keys.size == size` after all operations
+4. **Memory**: On Ruby >= 1.9, verify no `@keys` array allocated
+5. **Marshal**: Verify Maps serialize/deserialize within same Ruby version
+6. **Subclass inheritance**: Verify Map::Options exhibits same ordering behavior as Map
+
+## Edge Cases
+
+1. **Empty Map**: Should work identically in both configurations (no keys, no @keys)
+2. **Marshal across versions**: May fail or produce inconsistent state (documented limitation)
+3. **Forking**: `@keys` array duplicated in child process on Ruby < 1.9 (standard Ruby behavior)
+4. **Thread safety**: Same thread-safety guarantees as Hash (no additional synchronization)
+
+## Migration Path
+
+For users upgrading from older Ruby versions:
+
+1. **No code changes required**: API remains identical
+2. **Memory reduction automatic**: Ruby 1.9+ users get automatic optimization
+3. **Marshal incompatibility**: If loading Marshal dumps from Ruby 1.8.x on Ruby 1.9+:
+   - Workaround: `map.to_hash.to_map` to normalize
+   - Alternative: Use JSON/YAML for cross-version serialization

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

@@ -0,0 +1,139 @@
+# Implementation Plan: Conditional Ordered Map Module
+
+**Branch**: `001-ordered-map-module` | **Date**: 2025-11-10 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/001-ordered-map-module/spec.md`
+
+**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+Extract ordering-related code (using `@keys` array) into a separate module and conditionally include it only in Ruby versions where Hash is not ordered by default (Ruby < 1.9). This maintains backward compatibility for legacy Ruby versions while optimizing memory and performance for modern Ruby versions that have native Hash ordering. The implementation must preserve API compatibility and provide a simple testing mechanism to validate both code paths.
+
+## Technical Context
+
+**Language/Version**: Ruby 3.0+ (current minimum per gemspec), must support Ruby 1.8.x through 3.x behavior
+**Primary Dependencies**: None (map.rb is dependency-free per project philosophy)
+**Storage**: N/A (in-memory data structure library)
+**Testing**: Custom testing framework (test/lib/testing.rb) using `Testing` DSL
+**Target Platform**: Cross-Ruby (MRI 1.8.x through 3.x, JRuby, Rubinius, TruffleRuby)
+**Project Type**: Single Ruby gem library
+**Performance Goals**: Zero performance regression on Ruby 1.9+, maintain current performance on Ruby 1.8.x
+**Constraints**: No external dependencies, maintain existing test suite without modification, 100% backward API compatibility
+**Scale/Scope**: Core library with ~800 lines of code, ~200 test cases, used in production for 14+ years
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+**Status**: ✅ PASS - Constitution file is template-only, no specific project principles defined yet.
+
+This refactoring:
+- Maintains zero external dependencies (core map.rb principle)
+- Preserves 100% API compatibility (no breaking changes)
+- Uses existing test framework without modification
+- Follows KISS principle for testing mechanism
+- Improves code organization through modularization
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/speckit.plan command output)
+├── research.md          # Phase 0 output (/speckit.plan command)
+├── data-model.md        # Phase 1 output (/speckit.plan command)
+├── quickstart.md        # Phase 1 output (/speckit.plan command)
+├── contracts/           # Phase 1 output (/speckit.plan command)
+└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
+```
+
+### Source Code (repository root)
+
+```text
+lib/
+├── map.rb                    # Main Map class (modified: conditional module inclusion)
+├── map/
+│   ├── _lib.rb              # Utility methods
+│   ├── options.rb           # Map::Options subclass
+│   └── ordering.rb          # NEW: OrderingModule for legacy Ruby support
+
+test/
+├── map_test.rb              # Existing test suite (no modifications)
+├── lib/
+│   └── testing.rb           # Custom testing framework
+└── leak.rb                  # Memory leak tests
+```
+
+**Structure Decision**: Single gem library structure. The feature adds one new file (`lib/map/ordering.rb`) containing the extracted ordering module, and modifies the main `lib/map.rb` to conditionally include the module based on Ruby version detection. All existing files remain backward compatible.
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+N/A - No constitution violations. This is a simplification refactoring that reduces code complexity by conditionally including only necessary functionality.
+
+---
+
+## Phase 0: Research Complete ✅
+
+**Output**: [research.md](research.md)
+
+**Key Decisions**:
+- Ruby 1.9.0 version cutoff for conditional module inclusion
+- Use RUBY_VERSION constant for detection
+- Extract 11 ordering-dependent methods to Map::Ordering module
+- KISS testing via `MAP_FORCE_ORDERING=1` environment variable
+- Accept Marshal cross-version incompatibility as documented limitation
+
+**Status**: All technical unknowns resolved, ready for Phase 1 design.
+
+---
+
+## Phase 1: Design & Contracts Complete ✅
+
+### Artifacts Generated
+
+1. **[data-model.md](data-model.md)**: Internal state model documentation
+   - Two configurations: with/without `@keys` array
+   - State transitions and invariants
+   - Memory footprint analysis (25% savings on Ruby 1.9+)
+   - API compatibility matrix
+
+2. **contracts/**: N/A (internal refactoring, no external APIs)
+
+3. **[quickstart.md](quickstart.md)**: Developer guide
+   - Architecture diagrams
+   - Testing both code paths
+   - Code organization guidelines
+   - Troubleshooting guide
+
+### Constitution Check (Post-Phase 1) ✅
+
+**Status**: ✅ PASS - All design decisions align with project principles
+
+**Design Review**:
+- ✅ Zero external dependencies maintained
+- ✅ Backward compatibility preserved (100% API compatible)
+- ✅ Testing approach is KISS (single environment variable)
+- ✅ Code organization improved (separation of concerns via module)
+- ✅ Memory optimization achieved without breaking changes
+- ✅ Existing test suite requires no modifications
+
+**No violations identified** - The design enhances the codebase while maintaining all core principles.
+
+---
+
+## Next Steps
+
+The planning phase is complete. To proceed with implementation:
+
+1. Run `/speckit.tasks` to generate the implementation task list (tasks.md)
+2. Review and approve the generated tasks
+3. Execute tasks sequentially to implement the feature
+
+**Implementation will include**:
+- Creating `lib/map/ordering.rb` with extracted methods
+- Modifying `lib/map.rb` to conditionally include the module
+- Adding tests to verify both code paths
+- Updating documentation and CHANGELOG