Type-Safe Channel Routing for User Output

[josecelano]

Overview

Add compile-time type safety for channel routing (stdout vs stderr) in the UserOutput module by introducing newtype wrappers for writers. Currently, channel routing is done with runtime pattern matching which, while functional, doesn't provide compile-time guarantees that messages go to the correct channel.

This refactoring introduces StdoutWriter and StderrWriter newtype wrappers that make channel routing explicit in the type system, preventing accidental channel confusion at compile time.

Specification

See detailed specification: docs/issues/135-type-safe-channel-routing-for-user-output.md

🏗️ Architecture Requirements

DDD Layer: Presentation
Module Path: src/presentation/user_output.rs
Pattern: Type-safe wrappers using newtype pattern

Module Structure Requirements

• Follow module organization conventions (see docs/contributing/module-organization.md)
• Keep writer wrappers private as implementation details
• Maintain public API compatibility with existing code

Architectural Constraints

• Zero-cost abstraction using newtype pattern
• No runtime overhead compared to current implementation
• Preserve existing error handling behavior
• Error handling follows project conventions (see docs/contributing/error-handling.md)

Anti-Patterns to Avoid

• ❌ Exposing writer wrappers in public API unnecessarily
• ❌ Adding runtime checks when compile-time safety is available
• ❌ Breaking existing test infrastructure

Implementation Plan

Phase 1: Create Newtype Wrappers (30 minutes)

• Task 1.1: Create StdoutWriter newtype struct with documentation
• Task 1.2: Create StderrWriter newtype struct with documentation
• Task 1.3: Implement new() constructor for both wrappers
• Task 1.4: Implement write_line() method for both wrappers
• Task 1.5: Add unit tests for wrapper creation and writing

Phase 2: Update UserOutput Structure (45 minutes)

• Task 2.1: Update UserOutput struct fields to use typed wrappers
• Task 2.2: Add private helper methods write_to_stdout() and write_to_stderr()
• Task 2.3: Update all constructors to wrap writers in typed newtype
• Task 2.4: Update write() method to use typed writer helpers
• Task 2.5: Verify all existing public methods compile and work correctly

Phase 3: Update Tests (30 minutes)

• Task 3.1: Update test infrastructure to work with newtype wrappers
• Task 3.2: Add tests for type-safe channel routing
• Task 3.3: Verify all existing tests pass without modification
• Task 3.4: Add test cases demonstrating compile-time safety benefits

Phase 4: Documentation and Quality (30 minutes)

• Task 4.1: Update module documentation to mention type-safe routing
• Task 4.2: Add code examples showing type safety benefits
• Task 4.3: Run pre-commit checks and fix any issues
• Task 4.4: Verify documentation builds correctly

Acceptance Criteria

Note for Contributors: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.

Quality Checks:

• Pre-commit checks pass: ./scripts/pre-commit.sh
• All tests pass: cargo test
• Documentation builds: cargo doc --no-deps

Task-Specific Criteria:

• StdoutWriter and StderrWriter newtype wrappers are implemented
• Both wrappers have new() and write_line() methods
• UserOutput struct uses typed wrappers instead of raw Box<dyn Write>
• All constructors wrap raw writers in typed newtypes
• Private helper methods write_to_stdout() and write_to_stderr() exist
• The write() method uses typed helpers instead of direct writer access
• All existing tests pass without modification
• New tests demonstrate compile-time safety benefits
• Module documentation is updated to reflect type-safe routing
• Code examples show the benefits of the newtype pattern
• No performance regression (zero-cost abstraction)
• IDE autocomplete shows channel-specific methods

Related

• Parent: [EPIC] User Output Architecture Improvements #102 (Epic: User Output Architecture Improvements)
• Specification: docs/issues/135-type-safe-channel-routing-for-user-output.md
• Refactoring Plan: docs/refactors/plans/user-output-architecture-improvements.md