716 lines
19 KiB
Markdown
716 lines
19 KiB
Markdown
# zargs Implementation Plan
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
lib/zargs/
|
|
├── src/
|
|
│ ├── main.zig # Public API exports
|
|
│ ├── ArgumentRegistry.zig # Core registry implementation
|
|
│ ├── ArgumentType.zig # Type system and conversions
|
|
│ ├── parsing.zig # Argv parsing logic
|
|
│ ├── help.zig # Help text generation
|
|
│ └── metadata.zig # Metadata extraction from structs
|
|
├── tests/
|
|
│ ├── basic_test.zig # Basic functionality
|
|
│ ├── collision_test.zig # Type collision detection
|
|
│ ├── parsing_test.zig # Argument parsing
|
|
│ └── help_test.zig # Help generation
|
|
├── examples/
|
|
│ ├── simple.zig # Minimal example
|
|
│ ├── game_engine.zig # Multi-module game engine example
|
|
│ └── persistence.zig # Help text persistence example
|
|
├── research/ # Design documents (existing)
|
|
├── todo/ # Implementation tracking (current)
|
|
└── build.zig # Build configuration
|
|
```
|
|
|
|
## Phase 1: Core Type System (Week 1)
|
|
|
|
### 1.1 ArgumentType Implementation
|
|
**File:** `src/ArgumentType.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Define `ArgumentType` enum with all supported types
|
|
- [ ] `bool`, `u8`, `u16`, `u32`, `u64`
|
|
- [ ] `i8`, `i16`, `i32`, `i64`
|
|
- [ ] `string` ([]const u8)
|
|
- [ ] `string_list` ([]const []const u8)
|
|
- [ ] `enum_type` (for Zig enums)
|
|
- [ ] Implement `fromZigType(comptime T: type)` function
|
|
- [ ] Handle `bool`
|
|
- [ ] Handle integers with proper signedness/width detection
|
|
- [ ] Handle string slices
|
|
- [ ] Handle string list slices
|
|
- [ ] Handle enums
|
|
- [ ] Handle `?T` (optional) by unwrapping
|
|
- [ ] Provide clear compile errors for unsupported types
|
|
- [ ] Implement `matches(self, other)` for type compatibility
|
|
- [ ] Add unit tests for type detection
|
|
|
|
**Acceptance Criteria:**
|
|
- All Zig primitive types correctly map to ArgumentType
|
|
- Optional types unwrap correctly
|
|
- Clear compile errors for unsupported types (structs, unions, etc.)
|
|
- Type compatibility checker works correctly
|
|
|
|
**Estimated Time:** 1-2 days
|
|
|
|
---
|
|
|
|
### 1.2 ParsedValue Union
|
|
**File:** `src/ArgumentType.zig` (same file)
|
|
|
|
**Tasks:**
|
|
- [ ] Define `ParsedValue` tagged union
|
|
- [ ] Implement conversion functions:
|
|
- [ ] `fromString(arg_type: ArgumentType, s: []const u8, allocator: Allocator) !ParsedValue`
|
|
- [ ] `toTypedValue(comptime T: type, parsed: ParsedValue) T`
|
|
- [ ] Handle list parsing (comma-separated values)
|
|
- [ ] Handle enum parsing (string to enum value)
|
|
- [ ] Add unit tests for value conversions
|
|
|
|
**Acceptance Criteria:**
|
|
- String to typed value conversion works for all types
|
|
- Lists properly split on commas
|
|
- Enums parse from string names
|
|
- Error handling for invalid values
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
## Phase 2: Metadata System (Week 1)
|
|
|
|
### 2.1 Metadata Structures
|
|
**File:** `src/metadata.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Define `ArgumentMetadata` struct
|
|
- [ ] name, type, default_value_str
|
|
- [ ] short, long, help, value_name
|
|
- [ ] is_list flag
|
|
- [ ] source_location
|
|
- [ ] modules list (ArrayList)
|
|
- [ ] Define `ModuleInfo` struct
|
|
- [ ] name
|
|
- [ ] arguments list (ArrayList)
|
|
- [ ] Define `FieldMetadata` struct (for comptime extraction)
|
|
|
|
**Acceptance Criteria:**
|
|
- Structures compile and are well-documented
|
|
- Memory management strategy clear
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 2.2 Metadata Extraction
|
|
**File:** `src/metadata.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `extractFieldMetadata(comptime T: type, comptime field_name: []const u8)`
|
|
- [ ] Get `meta` decl if exists
|
|
- [ ] Extract short/long/help/value_name from meta
|
|
- [ ] Generate defaults if meta missing
|
|
- [ ] Convert field name to kebab-case for long form
|
|
- [ ] Implement `extractDocComment(comptime T: type, comptime field_name: []const u8) []const u8`
|
|
- [ ] Use doc comments as help text (if available in future Zig)
|
|
- [ ] Fallback to empty string for now
|
|
- [ ] Implement `formatDefaultValue(comptime T: type, value: T, allocator: Allocator) ![]const u8`
|
|
- [ ] Format bool as "true"/"false"
|
|
- [ ] Format integers as strings
|
|
- [ ] Format strings as-is
|
|
- [ ] Format enums as tag names
|
|
- [ ] Format lists as comma-separated
|
|
|
|
**Acceptance Criteria:**
|
|
- Can extract metadata from any valid struct
|
|
- Default values formatted correctly
|
|
- Missing meta declarations handled gracefully
|
|
|
|
**Estimated Time:** 1-2 days
|
|
|
|
---
|
|
|
|
## Phase 3: Core Registry (Week 2)
|
|
|
|
### 3.1 ArgumentRegistry Basic Structure
|
|
**File:** `src/ArgumentRegistry.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Define `ArgumentRegistry` struct with fields:
|
|
- [ ] allocator, arena
|
|
- [ ] arguments (StringHashMap)
|
|
- [ ] modules (StringHashMap)
|
|
- [ ] parsed_values (StringHashMap)
|
|
- [ ] parsed_structs (StringHashMap)
|
|
- [ ] argv cache
|
|
- [ ] help_requested flag
|
|
- [ ] Implement `init(allocator: Allocator) ArgumentRegistry`
|
|
- [ ] Implement `deinit(self: *ArgumentRegistry) void`
|
|
- [ ] Clean up all ArrayLists in modules
|
|
- [ ] Clean up all ArrayLists in arguments
|
|
- [ ] Deinit hashmaps
|
|
- [ ] Deinit arena
|
|
|
|
**Acceptance Criteria:**
|
|
- Registry initializes correctly
|
|
- No memory leaks (test with MemoryLeakDetector)
|
|
- All resources cleaned up properly
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 3.2 Help Request Detection
|
|
**File:** `src/ArgumentRegistry.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `isHelpRequested(self: *ArgumentRegistry) bool`
|
|
- [ ] Cache argv on first call
|
|
- [ ] Scan for "--help" or "-h"
|
|
- [ ] Set help_requested flag
|
|
- [ ] Return cached result on subsequent calls
|
|
|
|
**Acceptance Criteria:**
|
|
- Help detection works before any parsing
|
|
- Argv cached for later use
|
|
- No performance issues with repeated calls
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 3.3 Metadata Registration
|
|
**File:** `src/ArgumentRegistry.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `registerMetadata(self: *ArgumentRegistry, comptime T: type, opts: ParseOptions) !void`
|
|
- [ ] Get or create module entry
|
|
- [ ] Iterate over struct fields (comptime)
|
|
- [ ] Extract metadata for each field
|
|
- [ ] Check for existing arguments (collision detection)
|
|
- [ ] Error on incompatible type collisions with source locations
|
|
- [ ] Warn on compatible type collisions
|
|
- [ ] Add argument to module's list
|
|
- [ ] Store ArgumentMetadata in registry
|
|
|
|
**Acceptance Criteria:**
|
|
- Metadata correctly extracted from structs
|
|
- Compatible collisions allowed with warnings
|
|
- Incompatible collisions rejected with clear error messages
|
|
- Source locations captured and displayed in errors
|
|
|
|
**Estimated Time:** 2 days
|
|
|
|
---
|
|
|
|
### 3.4 Struct Already Parsed Check
|
|
**File:** `src/ArgumentRegistry.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement struct tracking in `parsed_structs` hashmap
|
|
- [ ] Use `@typeName(T)` as key
|
|
- [ ] Skip re-registration if already seen
|
|
|
|
**Acceptance Criteria:**
|
|
- Calling `parse()` twice with same struct is efficient
|
|
- No duplicate metadata registration
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
## Phase 4: Argument Parsing (Week 2-3)
|
|
|
|
### 4.1 Argv Parsing Infrastructure
|
|
**File:** `src/parsing.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `parseArgv(self: *ArgumentRegistry) !void`
|
|
- [ ] Get argv via `std.process.argsAlloc()` if not cached
|
|
- [ ] Skip program name
|
|
- [ ] Iterate over arguments
|
|
- [ ] Dispatch to appropriate parser
|
|
- [ ] Implement `parseArg(self: *ArgumentRegistry, arg: []const u8) !void`
|
|
- [ ] Handle `--long-name=value` format
|
|
- [ ] Handle `--long-name value` format (next arg)
|
|
- [ ] Handle `--flag` (boolean) format
|
|
- [ ] Look up argument metadata
|
|
- [ ] Parse value according to type
|
|
- [ ] Store in parsed_values
|
|
- [ ] Implement `parseShortArg(self: *ArgumentRegistry, short: u8) !void`
|
|
- [ ] Look up by short character
|
|
- [ ] Handle value if required
|
|
- [ ] Handle flag if boolean
|
|
|
|
**Acceptance Criteria:**
|
|
- All argument formats parsed correctly
|
|
- Unknown arguments produce clear errors
|
|
- Values parsed according to type
|
|
- Boolean flags don't require values
|
|
|
|
**Estimated Time:** 2 days
|
|
|
|
---
|
|
|
|
### 4.2 Value Parsing
|
|
**File:** `src/parsing.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement integer parsing with error handling
|
|
- [ ] Implement boolean parsing ("true"/"false", "1"/"0")
|
|
- [ ] Implement string parsing (already a string)
|
|
- [ ] Implement list parsing (split on comma)
|
|
- [ ] Implement enum parsing (string to enum tag)
|
|
- [ ] Handle parsing errors with useful messages
|
|
|
|
**Acceptance Criteria:**
|
|
- All types parse correctly from strings
|
|
- Clear errors for invalid values
|
|
- Edge cases handled (empty strings, invalid numbers, etc.)
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 4.3 Struct Reconstruction
|
|
**File:** `src/ArgumentRegistry.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `reconstructStruct(self: *ArgumentRegistry, comptime T: type) T`
|
|
- [ ] Create uninitialized struct
|
|
- [ ] Iterate over fields (comptime)
|
|
- [ ] Look up parsed value by long name
|
|
- [ ] Convert ParsedValue to field type
|
|
- [ ] Fall back to default if not parsed
|
|
- [ ] Return completed struct
|
|
|
|
**Acceptance Criteria:**
|
|
- Structs correctly populated with parsed values
|
|
- Defaults used when arguments not provided
|
|
- Type conversions work correctly
|
|
- All fields properly initialized
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 4.4 Main parse() Function
|
|
**File:** `src/ArgumentRegistry.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `parse(self: *ArgumentRegistry, comptime T: type, opts: ParseOptions) !T`
|
|
- [ ] Check if already parsed (use parsed_structs)
|
|
- [ ] If not, register metadata
|
|
- [ ] Parse argv (only new arguments)
|
|
- [ ] Reconstruct and return struct
|
|
- [ ] Mark struct as parsed
|
|
|
|
**Acceptance Criteria:**
|
|
- Complete parse flow works end-to-end
|
|
- Lazy parsing only processes new arguments
|
|
- Subsequent calls return cached results efficiently
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
## Phase 5: Help Generation (Week 3)
|
|
|
|
### 5.1 Help Text Formatting
|
|
**File:** `src/help.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Implement `getUsageAlloc(self: *ArgumentRegistry, allocator: Allocator) ![]const u8`
|
|
- [ ] Write header ("Usage: [OPTIONS]")
|
|
- [ ] Write global options (--help)
|
|
- [ ] Group arguments by module
|
|
- [ ] Format each argument:
|
|
- [ ] `-s, --long-name <VALUE>`
|
|
- [ ] Help text
|
|
- [ ] Default value
|
|
- [ ] Return allocated string
|
|
|
|
**Acceptance Criteria:**
|
|
- Help text is well-formatted and readable
|
|
- Arguments grouped by module
|
|
- Defaults shown for all arguments
|
|
- Short and long forms displayed correctly
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 5.2 Help Text Alignment
|
|
**File:** `src/help.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Calculate maximum width of argument specifications
|
|
- [ ] Align help text in columns
|
|
- [ ] Handle line wrapping for long help text
|
|
- [ ] Ensure consistent spacing
|
|
|
|
**Acceptance Criteria:**
|
|
- Help text looks professional
|
|
- Columns aligned nicely
|
|
- Readable on standard terminal widths
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
## Phase 6: Public API (Week 3)
|
|
|
|
### 6.1 Main Module Exports
|
|
**File:** `src/main.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Export `ArgumentRegistry`
|
|
- [ ] Export `ArgumentType`
|
|
- [ ] Export `ParsedValue`
|
|
- [ ] Export helper types (ParseOptions, etc.)
|
|
- [ ] Add top-level documentation
|
|
- [ ] Define version constant
|
|
|
|
**Acceptance Criteria:**
|
|
- All public types accessible
|
|
- API is clean and well-documented
|
|
- Version information available
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 6.2 Global Registry Helper
|
|
**File:** `src/main.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Consider providing helper to initialize global registry
|
|
- [ ] Document pattern for global usage
|
|
- [ ] Provide example code
|
|
|
|
**Acceptance Criteria:**
|
|
- Clear guidance on using global singleton
|
|
- Thread safety considerations documented
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
## Phase 7: Testing (Week 4)
|
|
|
|
### 7.1 Unit Tests
|
|
**Files:** `tests/*.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Test type detection and conversion
|
|
- [ ] Test metadata extraction
|
|
- [ ] Test argument parsing (all formats)
|
|
- [ ] Test collision detection (compatible and incompatible)
|
|
- [ ] Test help generation
|
|
- [ ] Test struct reconstruction
|
|
- [ ] Test list parsing
|
|
- [ ] Test enum parsing
|
|
- [ ] Test error conditions
|
|
|
|
**Acceptance Criteria:**
|
|
- 100% code coverage of core logic
|
|
- All edge cases tested
|
|
- Clear test names and documentation
|
|
|
|
**Estimated Time:** 2 days
|
|
|
|
---
|
|
|
|
### 7.2 Integration Tests
|
|
**Files:** `tests/*.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Test full parse cycle with multiple structs
|
|
- [ ] Test module registration order independence
|
|
- [ ] Test argv caching behavior
|
|
- [ ] Test help request before parsing
|
|
- [ ] Test help text persistence workflow
|
|
|
|
**Acceptance Criteria:**
|
|
- End-to-end workflows tested
|
|
- Multiple modules interacting correctly
|
|
- Real-world scenarios covered
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 7.3 Memory Leak Testing
|
|
**Files:** `tests/*.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Wrap all tests with memory leak detection
|
|
- [ ] Test cleanup paths (deinit)
|
|
- [ ] Test error paths (proper cleanup on errors)
|
|
- [ ] Verify arena allocator usage
|
|
|
|
**Acceptance Criteria:**
|
|
- Zero memory leaks in all tests
|
|
- All allocations properly freed
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
## Phase 8: Examples and Documentation (Week 4)
|
|
|
|
### 8.1 Simple Example
|
|
**File:** `examples/simple.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Single struct with basic types
|
|
- [ ] Parse and print values
|
|
- [ ] Show help usage
|
|
- [ ] Document every step
|
|
|
|
**Acceptance Criteria:**
|
|
- Works as minimal starting point
|
|
- Clear and easy to understand
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 8.2 Game Engine Example
|
|
**File:** `examples/game_engine.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Multiple modules (Engine, Physics, Audio, Renderer)
|
|
- [ ] Each module has its own Args struct
|
|
- [ ] Show scattered parsing pattern
|
|
- [ ] Generate help text
|
|
- [ ] Demonstrate compatible collisions
|
|
|
|
**Acceptance Criteria:**
|
|
- Realistic game engine scenario
|
|
- Shows plugin architecture usage
|
|
- Help text properly grouped
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 8.3 Persistence Example
|
|
**File:** `examples/persistence.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Generate help text after parsing
|
|
- [ ] Write to file
|
|
- [ ] Show embedding with @embedFile
|
|
- [ ] Fast --help response
|
|
|
|
**Acceptance Criteria:**
|
|
- Demonstrates novel persistence feature
|
|
- Shows workflow for production usage
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 8.4 README and API Documentation
|
|
**Files:** `README.md`, doc comments
|
|
|
|
**Tasks:**
|
|
- [ ] Write comprehensive README
|
|
- [ ] What is zargs?
|
|
- [ ] Why use it?
|
|
- [ ] Quick start guide
|
|
- [ ] Design philosophy
|
|
- [ ] Comparison to alternatives
|
|
- [ ] Document all public APIs with doc comments
|
|
- [ ] Add usage examples to doc comments
|
|
- [ ] Document design decisions
|
|
|
|
**Acceptance Criteria:**
|
|
- README is compelling and informative
|
|
- All public APIs documented
|
|
- Examples included in docs
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
## Phase 9: Build System (Week 4)
|
|
|
|
### 9.1 Build.zig Setup
|
|
**File:** `build.zig`
|
|
|
|
**Tasks:**
|
|
- [ ] Define library module
|
|
- [ ] Add test step
|
|
- [ ] Add example build steps
|
|
- [ ] Add install step
|
|
- [ ] Configure for Zig 0.14
|
|
|
|
**Acceptance Criteria:**
|
|
- `zig build` compiles library
|
|
- `zig build test` runs all tests
|
|
- `zig build run-simple` runs simple example
|
|
- Works with Zig 0.14
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 9.2 Integration with Backlog Engine
|
|
**File:** Integration into main project
|
|
|
|
**Tasks:**
|
|
- [ ] Import as lib/zargs module
|
|
- [ ] Make available to engine modules
|
|
- [ ] Test with actual engine code
|
|
- [ ] Document engine-specific patterns
|
|
|
|
**Acceptance Criteria:**
|
|
- Engine can use zargs
|
|
- Works with existing build system
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
## Phase 10: Polish and Release (Week 5)
|
|
|
|
### 10.1 Error Messages
|
|
**Tasks:**
|
|
- [ ] Review all error messages
|
|
- [ ] Ensure helpful and actionable
|
|
- [ ] Include context (argument name, module, source location)
|
|
- [ ] Format consistently
|
|
|
|
**Acceptance Criteria:**
|
|
- User-friendly error messages
|
|
- Easy to debug issues
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 10.2 Performance Testing
|
|
**Tasks:**
|
|
- [ ] Benchmark parsing overhead
|
|
- [ ] Benchmark help generation
|
|
- [ ] Profile memory usage
|
|
- [ ] Optimize hot paths if needed
|
|
|
|
**Acceptance Criteria:**
|
|
- Parsing overhead negligible
|
|
- Help generation fast
|
|
- Memory usage reasonable
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
### 10.3 Edge Cases
|
|
**Tasks:**
|
|
- [ ] Test with empty argv
|
|
- [ ] Test with no arguments defined
|
|
- [ ] Test with only --help
|
|
- [ ] Test with very long argument lists
|
|
- [ ] Test with unicode in arguments
|
|
- [ ] Test with special characters
|
|
|
|
**Acceptance Criteria:**
|
|
- No crashes on edge cases
|
|
- Reasonable behavior
|
|
|
|
**Estimated Time:** 0.5 days
|
|
|
|
---
|
|
|
|
### 10.4 Final Review
|
|
**Tasks:**
|
|
- [ ] Code review entire implementation
|
|
- [ ] Check for TODOs
|
|
- [ ] Verify all tests pass
|
|
- [ ] Run formatter
|
|
- [ ] Check for memory leaks
|
|
- [ ] Update documentation
|
|
|
|
**Acceptance Criteria:**
|
|
- Code is production-ready
|
|
- No known issues
|
|
|
|
**Estimated Time:** 1 day
|
|
|
|
---
|
|
|
|
## Timeline Summary
|
|
|
|
| Phase | Duration | Milestone |
|
|
|-------|----------|-----------|
|
|
| 1. Core Type System | 2-3 days | Type detection working |
|
|
| 2. Metadata System | 1.5-2.5 days | Metadata extraction working |
|
|
| 3. Core Registry | 4 days | Registry structure complete |
|
|
| 4. Argument Parsing | 5 days | End-to-end parsing working |
|
|
| 5. Help Generation | 1.5 days | Help text generation working |
|
|
| 6. Public API | 1 day | API finalized |
|
|
| 7. Testing | 3.5 days | Full test coverage |
|
|
| 8. Examples & Docs | 3 days | Documentation complete |
|
|
| 9. Build System | 1 day | Build integration complete |
|
|
| 10. Polish & Release | 3 days | Production ready |
|
|
|
|
**Total Estimated Time:** ~25 days (5 weeks)
|
|
|
|
## Success Criteria
|
|
|
|
- [ ] All unit tests pass
|
|
- [ ] All integration tests pass
|
|
- [ ] Zero memory leaks
|
|
- [ ] All examples run correctly
|
|
- [ ] Documentation complete and clear
|
|
- [ ] Can parse arguments from multiple modules
|
|
- [ ] Compatible collisions work
|
|
- [ ] Incompatible collisions error appropriately
|
|
- [ ] Help text generation works
|
|
- [ ] Help text persistence workflow demonstrated
|
|
- [ ] Integration with Backlog engine successful
|
|
|
|
## Risks and Mitigations
|
|
|
|
| Risk | Impact | Mitigation |
|
|
|------|--------|------------|
|
|
| Comptime complexity too high | High | Start simple, iterate; use runtime where needed |
|
|
| Memory management issues | High | Test early with leak detection; use arena allocator |
|
|
| Type system edge cases | Medium | Comprehensive type testing; clear error messages |
|
|
| Help text formatting tricky | Low | Reference existing tools; iterate on format |
|
|
| Integration issues | Medium | Test integration early in Phase 9 |
|
|
|
|
## Open Questions
|
|
|
|
1. Should we support positional arguments in v2? (deferred to v1 feedback)
|
|
2. Should we support config file loading? (separate feature, later)
|
|
3. Should we support environment variable fallback? (separate feature, later)
|
|
4. What about shell completion generation? (v2 feature)
|
|
5. How to handle argument value validation? (v2 feature - validators)
|
|
|
|
## Dependencies
|
|
|
|
- Zig 0.14
|
|
- No external dependencies (pure std lib)
|
|
|
|
## Testing Strategy
|
|
|
|
1. **Unit tests** - Test individual components in isolation
|
|
2. **Integration tests** - Test component interactions
|
|
3. **Example tests** - Ensure examples compile and run
|
|
4. **Memory tests** - Verify no leaks with GeneralPurposeAllocator
|
|
5. **Manual testing** - Test with Backlog engine integration
|
|
|
|
## Notes
|
|
|
|
- Keep implementation simple and focused on core use case
|
|
- Prioritize game engine / plugin architecture scenario
|
|
- Document design decisions and tradeoffs
|
|
- Write tests alongside implementation (TDD where appropriate)
|
|
- Get feedback early from engine integration
|