228 lines
5.5 KiB
Markdown
228 lines
5.5 KiB
Markdown
# Implementation Plan Review - Iteration 1
|
|
|
|
## Issues Found & Improvements
|
|
|
|
### 1. Missing Critical Component: String Interning/Storage
|
|
**Problem:** The plan doesn't address how we store string keys and values efficiently.
|
|
|
|
**Impact:** High - affects memory management and performance
|
|
|
|
**Solution:** Add Phase 1.3 for string storage strategy
|
|
- Use arena allocator for all strings
|
|
- Duplicate keys for hashmaps
|
|
- Clear ownership model
|
|
|
|
---
|
|
|
|
### 2. Incomplete Error Handling Strategy
|
|
**Problem:** Error types not defined upfront
|
|
|
|
**Impact:** Medium - will cause refactoring later
|
|
|
|
**Solution:** Add to Phase 1:
|
|
- Define error set in ArgumentType.zig
|
|
- `error{ IncompatibleArgumentType, UnknownArgument, InvalidValue, ... }`
|
|
- Document error semantics
|
|
|
|
---
|
|
|
|
### 3. Missing: Argument Name Conversion Logic
|
|
**Problem:** Need to convert field_name -> kebab-case for --long-name
|
|
|
|
**Impact:** Medium - affects usability
|
|
|
|
**Solution:** Add to Phase 2.2:
|
|
- Implement `toKebabCase(comptime name: []const u8) []const u8`
|
|
- Handle common patterns (fooBar -> foo-bar)
|
|
|
|
---
|
|
|
|
### 4. List Parsing Details Unclear
|
|
**Problem:** How do we handle repeated arguments? `--files=a.txt --files=b.txt`
|
|
|
|
**Impact:** Medium - affects API design
|
|
|
|
**Solution:** Clarify in Phase 4.2:
|
|
- Support both comma-separated AND repeated args
|
|
- Accumulate into list
|
|
- Document precedence
|
|
|
|
---
|
|
|
|
### 5. Collision Warning Implementation Missing
|
|
**Problem:** Plan says "warn" but doesn't specify how
|
|
|
|
**Impact:** Low - but affects UX
|
|
|
|
**Solution:** Add to Phase 3.3:
|
|
- Use `std.log.warn()` for compatible collisions
|
|
- Ensure warnings only shown once per argument
|
|
- Consider quiet mode for production
|
|
|
|
---
|
|
|
|
### 6. Type Conversion Safety
|
|
**Problem:** What if ParsedValue type doesn't match field type?
|
|
|
|
**Impact:** High - affects correctness
|
|
|
|
**Solution:** Add to Phase 4.3:
|
|
- Assert type compatibility at comptime
|
|
- Runtime check for dynamic cases
|
|
- Clear error if mismatch
|
|
|
|
---
|
|
|
|
### 7. Testing Order
|
|
**Problem:** Testing in Phase 7 means no tests until week 4
|
|
|
|
**Impact:** High - integration issues caught late
|
|
|
|
**Solution:** Reorder:
|
|
- Write tests alongside implementation
|
|
- Test-driven development for core components
|
|
- Phase 7 becomes "comprehensive test suite"
|
|
|
|
---
|
|
|
|
### 8. Source Location Storage
|
|
**Problem:** `std.builtin.SourceLocation` contains `file: []const u8` - who owns this?
|
|
|
|
**Impact:** Medium - potential memory issue
|
|
|
|
**Solution:** Add to Phase 3.3:
|
|
- SourceLocation strings are compile-time constants
|
|
- No need to duplicate
|
|
- Document this invariant
|
|
|
|
---
|
|
|
|
### 9. argv Ownership
|
|
**Problem:** Who owns the argv strings? How long are they valid?
|
|
|
|
**Impact:** High - potential use-after-free
|
|
|
|
**Solution:** Add to Phase 4.1:
|
|
- `argsAlloc()` allocates - we own it
|
|
- Store in registry, free in deinit
|
|
- All parsed strings must be duplicated into arena
|
|
|
|
---
|
|
|
|
### 10. Help Text Performance
|
|
**Problem:** Generating help text every time could be slow
|
|
|
|
**Impact:** Low - help is infrequent
|
|
|
|
**Solution:** Note in Phase 5.1:
|
|
- Acceptable to regenerate each time
|
|
- Could add caching later if needed
|
|
|
|
---
|
|
|
|
### 11. Module Name Storage
|
|
**Problem:** Module names in ParseOptions - are they string literals?
|
|
|
|
**Impact:** Medium - affects API
|
|
|
|
**Solution:** Clarify in Phase 3.3:
|
|
- Expect compile-time string literals
|
|
- Document that runtime strings need to be stable
|
|
- Consider copying to arena for safety
|
|
|
|
---
|
|
|
|
### 12. Optional Field Handling
|
|
**Problem:** How do we handle `?T` fields - always optional arguments?
|
|
|
|
**Impact:** Medium - affects API semantics
|
|
|
|
**Solution:** Add to Phase 4.3:
|
|
- `?T` means argument is optional
|
|
- `nil` if not provided
|
|
- Non-optional fields must have defaults (already required)
|
|
|
|
---
|
|
|
|
## Revised Phases
|
|
|
|
### New Phase Order:
|
|
|
|
**Week 1:**
|
|
- Phase 1: Core Type System + Error Types (3 days)
|
|
- Phase 2: Metadata System + String Handling (2 days)
|
|
|
|
**Week 2:**
|
|
- Phase 3: Core Registry (4 days)
|
|
- Start Phase 4: Argument Parsing (1 day)
|
|
|
|
**Week 3:**
|
|
- Finish Phase 4: Argument Parsing (4 days)
|
|
- Phase 5: Help Generation (1 day)
|
|
|
|
**Week 4:**
|
|
- Phase 6: Public API (1 day)
|
|
- Phase 7: Comprehensive Testing (4 days)
|
|
|
|
**Week 5:**
|
|
- Phase 8: Examples & Docs (3 days)
|
|
- Phase 9: Build System (1 day)
|
|
- Phase 10: Polish (1 day)
|
|
|
|
---
|
|
|
|
## Critical Path Items
|
|
|
|
1. **Type System** - Everything depends on this
|
|
2. **Metadata Extraction** - Needed for registration
|
|
3. **Argument Parsing** - Core functionality
|
|
4. **Struct Reconstruction** - Completes the cycle
|
|
5. **Help Generation** - Key differentiator
|
|
|
|
These must work before moving forward.
|
|
|
|
---
|
|
|
|
## Risk Assessment Updates
|
|
|
|
### High Risk Items:
|
|
1. **Comptime metadata extraction** - Most complex part
|
|
- Mitigation: Build iteratively, test each type
|
|
|
|
2. **Memory management** - Easy to leak
|
|
- Mitigation: Arena for most things, test early
|
|
|
|
3. **Type conversion safety** - Runtime bugs possible
|
|
- Mitigation: Comptime checks where possible
|
|
|
|
### Medium Risk Items:
|
|
1. **String ownership** - Confusing
|
|
- Mitigation: Clear documentation, ownership model
|
|
|
|
2. **Collision detection** - Edge cases
|
|
- Mitigation: Comprehensive tests
|
|
|
|
### Low Risk Items:
|
|
1. **Help formatting** - Mostly cosmetic
|
|
2. **Build integration** - Well-understood
|
|
|
|
---
|
|
|
|
## Confidence Level: 85%
|
|
|
|
**Strengths:**
|
|
- Clear phase breakdown
|
|
- Reasonable timeline
|
|
- Covers all requirements
|
|
- Identified most risks
|
|
|
|
**Concerns:**
|
|
- Comptime complexity might be underestimated
|
|
- String handling needs more thought
|
|
- Test-driven approach should be emphasized more
|
|
|
|
**Recommendation:**
|
|
- Address string handling first (Phase 1.3)
|
|
- Write tests alongside implementation
|
|
- Build simplest possible version first, then iterate
|