Proposal 8: Builder Pattern for Complex Messages

[josecelano]

Overview

Add optional builder patterns for complex message types in the UserOutput module. This proposal introduces builders that provide a fluent API for constructing complex messages while maintaining backward compatibility with simple direct construction.

Specification

See detailed specification: docs/issues/139-builder-pattern-for-complex-messages.md

Goals

• Create builder pattern for StepsMessage with fluent API
• Create builder pattern for InfoBlockMessage with fluent API
• Maintain backward compatibility with simple constructors
• Enable future extensibility with optional parameters
• Provide ergonomic API for common use cases
• Document when to use builders vs simple constructors

Implementation Plan

Phase 1: StepsMessageBuilder Implementation (1 hour)

• Create StepsMessageBuilder struct
• Implement new(), add(), and build() methods
• Add StepsMessage::builder() convenience method
• Keep existing StepsMessage::new() constructor

Phase 2: InfoBlockMessageBuilder Implementation (1 hour)

• Create InfoBlockMessageBuilder struct
• Implement new(), add_line(), and build() methods
• Add InfoBlockMessage::builder() convenience method

Phase 3: Testing (1.5 hours)

• Add tests for fluent API usage
• Add tests for direct construction (ensure backward compatibility)
• Add tests for empty builders
• Add integration tests showing formatting with builders

Phase 4: Documentation and Quality (30 minutes)

• Update module documentation with builder examples
• Document when to use builders vs simple constructors
• Run ./scripts/pre-commit.sh and fix any issues

Total Estimated Time: 4 hours

Acceptance Criteria

Functional Requirements

• StepsMessageBuilder provides fluent API for step messages
• InfoBlockMessageBuilder provides fluent API for info blocks
• Simple constructors remain available and unchanged
• Builders integrate seamlessly with OutputMessage trait
• Builder pattern is consuming (not mutating)

API Design Requirements

• Builder API is ergonomic and intuitive
• Method names are clear and follow Rust conventions
• builder() and new() methods coexist for different use cases

Testing Requirements

• Unit tests cover fluent API construction
• Tests verify backward compatibility with simple constructors
• Tests cover edge cases (empty builders, single item, many items)

Quality Requirements

• Pre-commit checks pass: ./scripts/pre-commit.sh
• Builder pattern follows Rust idioms
• No clippy warnings for builder implementation

Related

• Parent Epic: [EPIC] User Output Architecture Improvements #102 - User Output Architecture Improvements
• Refactoring Plan: docs/refactors/plans/user-output-architecture-improvements.md
• Depends On: Use Message Trait for Extensibility #127 - Use Message Trait for Extensibility

Labels

enhancement, phase-2, user-output, P2

Priority

P2 (Phase 2 - Polish & Extensions)

Estimated Effort

4 hours

[josecelano]

Parent Epic: #102 - User Output Architecture Improvements

This issue is part of Phase 2: Polish & Extensions of the User Output Architecture refactoring.