Skip to content

QA Analysis Overview

Date: 2025-11-08 Analysis Type: Quality Assurance (phpcs, phpmd, phpstan, rector) Status: Planning Phase - No Code Changes Yet

Executive Summary

This document provides an overview of all QA tool violations discovered via make qa and their prioritization. The errors have been classified into categories and prioritized based on:

  • Impact on code maintainability
  • Risk of bugs
  • Alignment with architecture principles
  • Effort required vs benefit gained

Error Statistics

Priority Count Category Focus
🔴 Critical 3 groups (7 files) God Objects, Extreme Complexity
🟠 High 4 groups (10 files) Domain Model, DTOs, Core Services
🟡 Medium 5 groups (10 files) Commands, Supporting Services
🟢 Low 6 groups (varies) Fixtures, Minor Violations, Infrastructure

Error Categories

1. Excessive Complexity (PHPMD - Cyclomatic & NPath)

18 violations across Commands, Services, and Repositories. These indicate methods with too many conditional branches and execution paths, making them difficult to test and maintain.

2. God Objects & Excessive Class Complexity (PHPMD)

4 violations in core classes:

  • HtmlCleaner (107/60) - MOST SEVERE
  • FilterService (83/60)
  • EntityToDtoMapper (63/60)
  • CoffeeBean entity (74/60)

3. Excessive Method Length (PHPMD)

3 violations in Commands and Fixtures (150-229 lines), violating the guideline of methods >30 lines.

4. Excessive Parameter Lists (PHPMD)

5 violations in DTOs and Services (9-22 parameters), with CoffeeBeanDTO being the worst offender at 22 parameters.

5. Side Effects (PHPCS)

1 PSR-1 violation in configuration script.

6. Type Safety Issues (PHPStan)

Multiple violations (output truncated) - requires separate detailed analysis.

7. Rector Suggestions

Output truncated - requires separate analysis for modernization opportunities.

Priority Breakdown

🔴 CRITICAL PRIORITY (Address Immediately)

C1: HtmlCleaner God Object

  • File: Service/Crawler/HtmlCleaner.php
  • Complexity: 107/60 (EXTREME)
  • Impact: Core crawler functionality, affects data quality platform-wide
  • Plan: refactor-html-cleaner-god-object.md

C2: FilterService God Object

  • File: Service/Api/FilterService.php
  • Complexity: 83/60
  • Impact: Core API functionality, affects user experience
  • Plan: refactor-filter-service-god-object.md

C3: Operational Command Complexity

  • Files:
    • Command/VerifyCacheConnectionCommand.php (CC: 21, 204 lines)
    • Command/ResumeCrawlsCommand.php (CC: 18, 150 lines)
  • Impact: Critical operational reliability
  • Plan: simplify-operational-commands.md

🟠 HIGH PRIORITY (Address Soon)

H1: Domain Entity & Mapper Complexity

  • Files:
    • Entity/CoffeeBean.php (74/60)
    • Service/Api/Mapper/EntityToDtoMapper.php (63/60)
  • Plan: simplify-domain-entities.md

H2: CoffeeBeanPersister Complexity

  • File: Service/Crawler/Persistance/CoffeeBeanPersister.php
  • Plan: refactor-coffee-bean-persister.md

H3: DTO Parameter Lists

  • Files: 4 DTOs with 9-22 parameters
  • Worst: CoffeeBeanDTO (22 parameters)
  • Plan: refactor-dto-parameter-lists.md

H4: Repository Complexity

  • File: Repository/VarietyRepository.php
  • Plan: simplify-variety-repository.md

🟡 MEDIUM PRIORITY (Address When Convenient)

See individual plans for:

  • refactor-crawler-commands.md - Remaining command complexity
  • refactor-url-services.md - URL handling services

🟢 LOW PRIORITY (Opportunistic)

  • Fixture complexity (test data, not production)
  • Minor repository violations (just over thresholds)
  • PSR-1 config script violation
  • Type safety issues (requires full analysis)
  • Rector suggestions (requires full analysis)

Guideline Violations

All Critical and High priority items directly violate project guidelines:

  • God Objects Anti-pattern: HtmlCleaner, FilterService, CoffeeBean, EntityToDtoMapper
  • Long Methods Anti-pattern: Commands with 150+ lines (guideline: <30 lines)
  • SOLID - Single Responsibility Principle: Most complexity violations
  • Design Best Practices: Excessive parameter lists

  1. Phase 1 (Critical): God objects and operational commands

    • Blocks: Feature development in affected areas
    • Timeline: Immediate

  2. Phase 2 (High): Domain model, DTOs, core services

    • Blocks: API changes, new features
    • Timeline: Short-term (next sprint)

  3. Phase 3 (Medium): Supporting services and remaining commands

    • Improves: Developer experience, maintainability
    • Timeline: Medium-term (next quarter)

  4. Phase 4 (Low): Opportunistic improvements

    • Address: During related refactoring
    • Timeline: As convenient

Next Steps

  1. Review individual plan files for detailed refactoring strategies
  2. Obtain full PHPStan and Rector output for complete analysis
  3. Establish test coverage baselines before refactoring
  4. Begin with Critical priority items

Notes

  • This analysis does not include code changes - only classification and prioritization
  • Type safety and Rector analyses are incomplete due to truncated output
  • All refactoring should be preceded by test coverage improvements
  • Sequential dependencies exist between some refactorings