feat(Modern): add help formatting system (Week 5)

[ralflang]

Summary

Add professional help formatting system to Modern API. This completes the Modern API implementation with full help text generation capabilities.

Changes

HelpFormatter Implementation

• Immutable help formatter with builder pattern
• Terminal-width-aware text wrapping
• Auto-detection of terminal width (fallback to 80)
• Configurable indentation and alignment
• Support for usage, description, epilog, options, and groups

Parser Integration

• formatHelp() method on ImmutableParser
• Optional custom formatter support
• Uses builder-provided formatter if available
• Falls back to default formatter

Features

Formatting Capabilities:

• Usage line with %prog substitution
• Description and epilog text wrapping
• Option alignment with configurable column position
• Automatic default value display
• Automatic choices display
• Metavar support for argument placeholders
• Option groups with headers and descriptions

Customization:

• withWidth(int): Set terminal width
• withIndent(int): Set indentation increment
• withMaxHelpPosition(int): Set help column position
• withShortFirst(bool): Control option ordering

Example Output:

Usage: converter [options] <input> <output>

Convert files between formats

Options:
  -v, --verbose         Increase verbosity
  -p, --port=PORT       Server port (default: 8080)
  -f, --format=FORMAT   Output format (choices: 'json', 'xml', 'csv')
                        (default: json)

Debugging:
  -d, --debug           Enable debug mode
  -t, --trace           Enable trace output

For more information, visit https://example.com

Test Coverage

✓ 28 new tests (234 total Modern API tests)
✓ 73 new assertions (403 total assertions)
✓ 100% passing

Test Coverage Includes:

• Formatter creation and immutability
• All formatting scenarios (usage, description, epilog, options, groups)
• Default value and choice display
• Custom width and indentation
• Short/long option ordering
• Parser integration
• Complete help generation

Design

Immutable Throughout:

• Readonly HelpFormatter class
• Builder pattern for configuration
• No side effects during formatting
• Thread-safe and cacheable

Clean Separation:

• Formatter is independent of parser
• Parser delegates to formatter
• Can swap formatters without changing parser

Performance:

• Fast formatting (no reflection)
• Efficient text wrapping algorithm
• Minimal memory allocations

Example Usage

use Horde\Argv\Modern\Builder\{ParserBuilder, OptionBuilder};
use Horde\Argv\Modern\Help\HelpFormatter;
use Horde\Argv\Modern\Enum\OptionType;

$verbose = OptionBuilder::create()
    ->short('-v')->long('--verbose')
    ->counter()->help('Increase verbosity')
    ->build();

$port = OptionBuilder::create()
    ->short('-p')->long('--port')
    ->type(OptionType::Int)->default(8080)
    ->help('Server port')
    ->build();

$parser = ParserBuilder::create()
    ->withUsage('%prog [options] <file>')
    ->withDescription('Process files')
    ->addOption($verbose)
    ->addOption($port)
    ->build();

// Default formatter
echo $parser->formatHelp();

// Custom formatter
$formatter = HelpFormatter::create()->withWidth(100);
echo $parser->formatHelp($formatter);

Status

Modern API is now feature-complete:

• ✅ Enums (Week 1)
• ✅ Config objects (Week 1)
• ✅ Result objects (Week 2)
• ✅ Exceptions (Week 2)
• ✅ Validators (Week 2)
• ✅ Builders (Week 3)
• ✅ Parser (Week 4)
• ✅ Help formatting (Week 5)

The Modern API is production-ready with full parsing, validation, and help generation!

Checklist

• All tests passing (234/234)
• PHPDoc complete
• Type declarations on all methods
• Conventional commit message
• No breaking changes
• Immutability verified
• Integration tested