feat: Implement semantic types for parser system (CLI-11)

[dugshub]

Summary

Implements semantic types for the parser system following Test-Driven Development, providing compile-time type safety and preventing type confusion.

Changes

• Core semantic types: CommandId, OptionKey, FlagName, ArgumentValue, ParseMode, ContextKey
• Parser integration: SemanticParseResult, SemanticContext with full conversion support
• Error handling: Enhanced error types with semantic context
• Command registry: Type-safe command management with fuzzy suggestions
• Parser implementation: Complete semantic parser and pipeline
• Comprehensive tests: 55 new tests covering all components

Benefits

• ✅ Compile-time type safety prevents mixing CommandId with OptionKey
• ✅ Better IDE support with semantic autocomplete
• ✅ Self-documenting code through meaningful types
• ✅ Zero runtime overhead (simple NewType approach)
• ✅ Full backward compatibility with conversion methods

Test Results

• 55 new tests all passing
• MyPy strict mode: 0 errors
• All quality checks: passing (format, lint, type-check, test)
• Total test suite: 495 tests passing

Implementation Notes

• Follows CLI Patterns architecture with protocol-based design
• Maintains stateless execution principles
• Simple NewType approach avoiding runtime complexity
• Full interoperability with existing parser system

Closes #CLI-11

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[dugshub]

@claude - review this PR

[claude]

Claude finished @dugshub's task —— View job

---

✅ Review Complete: Implement semantic types for parser system (CLI-11)

Overall Assessment ✅

Excellent implementation of semantic types for the parser system! This PR successfully introduces compile-time type safety to prevent type confusion while maintaining backward compatibility and zero runtime overhead. The implementation follows TDD practices with comprehensive test coverage.

Strengths 🎯

1. Clean Type System Design

• Simple NewType approach avoids runtime complexity (src/cli_patterns/core/parser_types.py)
• Well-organized semantic types: CommandId, OptionKey, FlagName, ArgumentValue, ParseMode, ContextKey
• Factory functions provide clear instantiation patterns
• Type aliases (CommandList, OptionDict, etc.) enhance readability

2. Seamless Integration

• SemanticParseResult and SemanticContext provide type-safe wrappers with bidirectional conversion methods (from_parse_result() / to_parse_result())
• Maintains full compatibility with existing parser system
• Clean protocol-based architecture preserved

3. Enhanced Error Handling

• SemanticParseError extends base error class with semantic type context (src/cli_patterns/ui/parser/semantic_errors.py:15-72)
• Preserves suggestions as semantic types while maintaining base class compatibility
• Rich error context with command, invalid_option, valid_options fields

4. Comprehensive Test Coverage

• 55 new tests covering all components
• Excellent test organization and documentation
• Tests verify type distinctness, equality, hashing, JSON serialization, and string operations
• Integration tests demonstrate end-to-end semantic type flow (tests/integration/test_parser_type_flow.py)

5. Developer Experience

• Better IDE support with semantic autocomplete
• Self-documenting code through meaningful type names
• Clear separation of concerns with dedicated semantic modules

Minor Suggestions for Improvement 💡

1. Documentation Enhancement

Consider adding a dedicated README or documentation section explaining:

• When to use semantic types vs regular strings
• Migration guide for existing code
• Best practices for extending the semantic type system

2. Type Shadowing in SemanticParseError

The intentional shadowing of suggestions attribute (semantic_errors.py:66) works but could be cleaner:

# Current: Type ignore comment
self.suggestions: list[CommandId] = suggestions or []  # type: ignore[assignment]

# Alternative: Consider using a different attribute name
self.semantic_suggestions: list[CommandId] = suggestions or []

3. Validation Opportunities

While the current implementation avoids runtime validation (good for performance), consider optional validation for development mode:

def make_command_id(value: str, validate: bool = False) -> CommandId:
    if validate and not value.strip():
        raise ValueError("Command ID cannot be empty")
    return CommandId(value)

4. Type Guard Functions

Consider adding type guard functions for runtime type checking when needed:

def is_command_id(value: Any) -> TypeGuard[CommandId]:
    return isinstance(value, str) and hasattr(value, '__class__')

Code Quality ✅

• MyPy Strict Mode: 0 errors - excellent type safety
• Code Organization: Clean separation into semantic modules
• Testing: Comprehensive coverage with well-structured tests
• Performance: Zero runtime overhead with NewType approach
• Backward Compatibility: Full interoperability maintained

Security & Best Practices ✅

• No security concerns identified
• Follows CLI Patterns architecture principles
• Maintains stateless execution model
• Proper error handling throughout

Conclusion

This is a high-quality PR that successfully implements semantic types for enhanced type safety. The implementation is clean, well-tested, and maintains full backward compatibility. The use of NewType provides compile-time safety without runtime overhead, which is the ideal approach for this use case.

Recommendation: Ready to merge! 🚀

The minor suggestions above are optional enhancements that could be addressed in future iterations. The current implementation is solid and provides immediate value to the codebase.

---

Great work on this implementation! The semantic types will significantly improve code maintainability and developer experience.

[dugshub]

@claude review the changes made tp address your feedback

[claude]

Claude finished @dugshub's task —— View job

---

✅ Review Complete: Changes Successfully Address All Feedback

Summary

Excellent work addressing all the feedback from the initial review! The changes in commit 89cfa10 comprehensively implement all four suggestions while maintaining the clean design and zero runtime overhead approach.

Changes Reviewed

1. ✅ Documentation Enhancement - FULLY ADDRESSED

Added comprehensive docs/semantic-types.md (292 lines) covering:

• Clear overview of semantic types and their purpose
• When to use semantic types vs regular strings
• Detailed migration guide with before/after examples
• Factory function usage and type aliases
• Best practices and code examples
• Error handling with semantic types

The documentation is well-structured, practical, and provides clear guidance for developers.

2. ✅ Type Shadowing Fix - CLEANLY RESOLVED

src/cli_patterns/ui/parser/semantic_errors.py:

• Changed from shadowing suggestions to using distinct semantic_suggestions attribute
• Added command_suggestions property for backward compatibility
• Removed type ignore comment for cleaner code

# Before: self.suggestions: list[CommandId] = suggestions  # type: ignore
# After: self.semantic_suggestions: list[CommandId] = suggestions

3. ✅ Validation Opportunities - WELL IMPLEMENTED

src/cli_patterns/core/parser_types.py:

• All factory functions now accept optional validate=False parameter
• Zero overhead by default (maintains performance)
• When validate=True, performs appropriate checks:
  • Empty value validation
  • Length limits (100 chars for IDs/keys, 1000 for arguments)
  • Format validation (options/flags must start with - or /)
  • Valid parse modes check

def make_command_id(value: str, validate: bool = False) -> CommandId:
    if validate:
        if not value or not value.strip():
            raise ValueError("Command ID cannot be empty")
        if len(value) > 100:
            raise ValueError("Command ID is too long (max 100 characters)")
    return CommandId(value)

4. ✅ Type Guard Functions - FULLY IMPLEMENTED

Added type guard functions for all semantic types:

• is_command_id(), is_option_key(), is_flag_name()
• is_argument_value(), is_parse_mode(), is_context_key()
• Uses TypeGuard from typing_extensions for proper type narrowing
• Clear documentation about runtime behavior

def is_command_id(value: Any) -> TypeGuard[CommandId]:
    """Check if a value is a CommandId at runtime."""
    return isinstance(value, str)

Code Quality

• CI Status: ✅ All tests passing (latest run successful)
• Test Updates: Tests properly updated to use semantic_suggestions instead of shadowed attribute
• Type Safety: Maintains MyPy strict mode compliance
• Performance: Zero runtime overhead preserved with opt-in validation

Conclusion

All feedback has been thoughtfully addressed with high-quality implementations. The changes enhance the semantic types system while maintaining the original design goals of simplicity and zero runtime overhead. The addition of comprehensive documentation will greatly help developers adopt and use semantic types correctly.

The PR is ready to merge! 🚀

Great job on the quick turnaround and thorough implementation of the feedback!