Backlog/lib/sdl3/parser/TODO.md

SDL3 Parser - Next Steps

Current Status ✅

The parser is complete and functional with:

• All C declaration types supported (opaque, enum, struct, flags, functions)
• Proper naming conventions implemented ("first underscore" rule)
• Memory leak free (validated with GPA)
• 18+ unit tests, all passing
• Comprehensive documentation under docs/
• Successfully parses SDL_gpu.h (169 declarations)

Next Implementation Phase

Based on TEST_HARNESS_PLAN_V2.md, the next logical steps are:

1. Implement Mock Code Generator (~3 hours)

Create mock_codegen.zig to generate C mock implementations when --mocks flag is passed:

zig build run -- SDL_gpu.h --mocks > gpu_mocks.c

Tasks:

• Add --mocks CLI flag parsing in parser.zig
• Create mock_codegen.zig module
• Generate stub C functions that return null/0/default values
• Generate C header declarations
• Add unit tests for mock generation

2. Create Test Project (~4 hours)

Build test_project/ with complete compilation and linkage testing:

Tasks:

• Create test_project/ directory structure
• Set up build.zig to compile C mocks into static library
• Create c.zig that links against mock library
• Generate Zig bindings from SDL_gpu.h
• Create test_main.zig that calls all generated functions
• Add assertions to verify function calls work
• Integrate into main build.zig as zig build test-project

3. Add Golden File Testing (~2 hours)

Implement regression testing to catch unintended output changes:

Tasks:

• Generate golden reference file from current parser output
• Create comparison test in test_project/
• Add diff reporting when output changes
• Add --update-golden flag to accept new output

4. Multi-Header Support (~2 hours)

Test parser on additional SDL3 headers:

Tasks:

• Test with SDL_video.h
• Test with SDL_audio.h
• Test with SDL_events.h
• Document any new patterns discovered
• Add pattern-specific tests if needed

Future Enhancements

Nice to Have

• Performance benchmarking and profiling
• Batch processing script for multiple headers
• CI/CD integration for automated testing
• Fuzz testing with random C headers
• Support for function pointer types (basic support exists)
• Support for union types
• Support for complex macros (beyond simple #define)

Documentation

• Add examples of using generated bindings in real projects
• Create video/tutorial for using the parser
• Document known limitations and unsupported patterns

Time Estimate

Test Harness Implementation: ~10 hours total

• Mock generator: 3 hours
• Test project: 4 hours
• Golden file testing: 2 hours
• Multi-header testing: 1 hour

Getting Started

To begin the next phase:

1. Read TEST_HARNESS_PLAN_V2.md for complete design
2. Start with mock code generator implementation
3. Use test-driven development (write tests first)
4. Run zig build test frequently to verify changes
5. Update this TODO.md as tasks are completed

Questions/Decisions Needed

• Should mocks return null/zero or track call counts?
• Should test project test all functions or just a subset?
• What's the acceptable diff threshold for golden file testing?
• Should we support C++ headers in the future?

---

Last updated: 2026-01-21 Parser version: Working, all tests passing