Refactor Builder.php and improve error messages

[dereuromark]

Summary

This PR addresses three high-priority issues:

• Refactor Builder.php into smaller focused classes #27 - Refactor Builder.php into smaller focused classes
• Add circular dependency detection #28 - Add circular dependency detection
• Improve error messages with contextual information #29 - Improve error messages with contextual information

New Classes Extracted from Builder.php

Class	Responsibility	Lines
TypeValidator	Validates types (names, DTOs, arrays, collections, interfaces/classes)	~180
TypeResolver	Resolves types (typehints, singular types, collection types, enum/serialize detection)	~170
ArrayShapeBuilder	Builds PHPDoc array shape types for DTOs	~210
DependencyAnalyzer	Detects circular dependencies using DFS	~230

Builder.php reduced from ~1,207 lines to ~850 lines.

Circular Dependency Detection

The new DependencyAnalyzer class:

• Builds a dependency graph from DTO definitions
• Uses depth-first search to detect cycles
• Provides clear error messages with the full cycle path

Example error:

Circular dependency detected: ParentDto -> ChildDto -> ParentDto
Hint: Consider making one of the fields nullable or using lazy loading to break the cycle.

Improved Error Messages

All error messages now include:

• The specific DTO name
• The field name (where applicable)
• A helpful "Hint:" with suggestions to fix the issue

Before:

Invalid type `Foo`

After:

Invalid type 'Foo' for field 'items' in 'OrderDto' DTO.
Hint: Valid types include: scalar types (int, string, bool, float), DTO references (OtherDto), arrays (string[], OtherDto[]), or fully qualified class names (\App\MyClass).

Test plan

• All existing tests pass (465 tests, 937 assertions)
• phpcs clean
• phpstan level 8 passes
• Updated test expectations to match new error messages

[codecov]

Codecov Report

❌ Patch coverage is 70.77626% with 128 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.86%. Comparing base (02c1ce4) to head (084c0ac).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Generator/Builder.php	47.19%	94 Missing ⚠️
src/Generator/DependencyAnalyzer.php	65.85%	28 Missing ⚠️
src/Generator/TypeResolver.php	94.54%	3 Missing ⚠️
src/Generator/TypeValidator.php	96.36%	2 Missing ⚠️
src/Generator/ArrayShapeBuilder.php	98.52%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master      #39      +/-   ##
============================================
- Coverage     86.92%   83.86%   -3.06%     
- Complexity     1009     1046      +37     
============================================
  Files            29       33       +4     
  Lines          2340     2554     +214     
============================================
+ Hits           2034     2142     +108     
- Misses          306      412     +106     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.