Skip to content

QA Analysis and Refactoring Plans

Analysis Date: 2025-11-08 Status: Planning Phase - No Code Changes Made

This directory contains comprehensive analysis and refactoring plans based on QA tool output (phpcs, phpmd, phpstan, rector).

Quick Start

Immediate Action Required 🔴

CRITICAL BUG DETECTED: Start with this plan immediately:

This Week (High Priority) 🟠

Execute these plans for maximum impact with minimal effort:

  1. add-doctrine-collection-generics.md - Quick win, fixes 69 errors
  2. apply-rector-safe-rules.md - Automated modernization
  3. refactor-html-cleaner-god-object.md - Worst complexity violation

Overview Documents

Master Analysis Documents

These provide executive summaries, statistics, and prioritization.

Plans by Priority

🔴 Critical Priority (Week 1)

Type Safety (PHPStan):

  1. fix-missing-default-instruction-method.md - Runtime error bug
  2. fix-undefined-methods.md - 24 potential runtime errors (To be created)
  3. fix-uninitialized-properties.md - Null reference bugs (To be created)

Complexity (PHPMD):

  1. refactor-html-cleaner-god-object.md - Complexity 107/60
  2. refactor-filter-service-god-object.md - Complexity 83/60
  3. simplify-operational-commands.md - Critical ops commands

🟠 High Priority (Week 2-3)

Type Safety:

  1. add-doctrine-collection-generics.md - 69 errors, quick win
  2. apply-rector-safe-rules.md - Automated modernization

Complexity:

  1. simplify-domain-entities.md - CoffeeBean & mapper
  2. refactor-coffee-bean-persister.md - Data ingestion
  3. refactor-dto-parameter-lists.md - 22 parameters!
  4. simplify-variety-repository.md - Query complexity

🟡 Medium Priority (Week 4-6)

Type Safety:

  1. add-array-type-hints-entities.md - 294 errors (To be created)
  2. add-array-type-hints-services.md (To be created)
  3. add-array-type-hints-repositories.md (To be created)
  4. fix-return-type-mismatches.md (To be created)

Complexity:

  1. refactor-crawler-commands.md - Command complexity
  2. refactor-url-services.md - URL handling

🟢 Low Priority (Opportunistic)

  1. exclude-deploy-from-phpstan.md - Config cleanup (To be created)
  2. Fixture complexity - Low priority (test data)
  3. PSR-1 violations - Config scripts

Plans by Category

God Objects & Complexity

Type Safety & PHPStan

Data Layer

API Layer

Crawler

Statistics

Current State (2025-11-08)

  • PHPMD Violations: 29

    • God Objects: 4 (complexity 63-107)
    • Excessive Complexity: 18 methods
    • Excessive Parameters: 5 DTOs/classes
    • Long Methods: 3 (150-229 lines)

  • PHPStan Errors: 635

    • Missing array types: 294 (46%)
    • Missing generics: 69 (11%)
    • Undefined methods: 24 (4%)
    • Uninitialized properties: 18 (3%)
    • deploy.php errors: 115 (18% - can ignore)

  • Rector Suggestions: 53 files

    • Safe modernizations available

Target State (1 Month)

  • PHPMD: <15 violations
  • PHPStan: <200 errors (68% reduction)
  • Critical Errors: 0
  • Type Coverage: ~70%

Target State (3 Months)

  • PHPMD: <5 violations
  • PHPStan: <50 errors (92% reduction)
  • Type Coverage: ~90%
  • PHPStan Level: 8

Quick Wins (High Impact, Low Effort)

Execute these first for maximum return on investment:

  1. add-doctrine-collection-generics.md

    • Effort: 2-3 hours
    • Impact: Fixes 69 PHPStan errors
    • Automated: 95% via Rector

  2. apply-rector-safe-rules.md

    • Effort: 2-3 hours
    • Impact: Fixes ~100 errors, modernizes code
    • Automated: 90% via Rector

  3. fix-missing-default-instruction-method.md

    • Effort: 2-3 hours
    • Impact: Prevents production crashes
    • Critical: Runtime bug

Week 1: Critical Bugs

  1. Fix missing getDefaultInstruction() method (P0)
  2. Investigate undefined method errors (P0)
  3. Fix uninitialized properties (P1)

Week 2: Quick Wins

  1. Add Doctrine Collection generics (automated)
  2. Apply safe Rector rules (automated)
  3. Start on HtmlCleaner god object

Week 3-4: Major Refactoring

  1. Complete HtmlCleaner refactoring
  2. Refactor FilterService god object
  3. Simplify operational commands
  4. Refactor DTOs with excessive parameters

Week 5-6: Medium Priority

  1. Domain entity simplification
  2. Coffee bean persister refactoring
  3. Repository query builders
  4. Array type hints (entities first)

Week 7+: Cleanup & Optimization

  1. Remaining array type hints
  2. Command simplification
  3. URL service refactoring
  4. Configuration cleanup

Tools Used

  • phpcs - Code style (PSR-1, PSR-12)
  • phpmd - Complexity and design violations
  • phpstan - Static analysis and type safety (Level 7)
  • rector - Code modernization and type hints

Notes

  • All plans are in planning phase - no code has been changed
  • Plans are independent where possible - can be executed in parallel
  • Some plans have dependencies - check individual plan files
  • Type safety and complexity refactoring can be done in parallel
  • Quick wins should be prioritized for morale and momentum
  • Critical bugs must be fixed before deployment

Getting Started

  1. Read the overview documents:

  2. Start with critical priority items:

  3. Get some quick wins:

  4. Tackle the big refactorings:

Contributing

When implementing these plans:

  1. Create a feature branch for each plan
  2. Follow the implementation steps in the plan
  3. Run all tests and QA tools
  4. Update the plan with any discoveries
  5. Mark plan as "Implemented" when complete
  6. Update this README with new metrics

Questions?

Review the detailed analysis and architect recommendations in the overview documents.