Date: November 12, 2026
Baseline: v1.2.4 (phpcs 23/23 passing, tests/run.php 113/113 assertions passing)
Following rapid feature delivery across 1.1.0–1.2.4 (Readiness Verdict UX, WordPress.org fix verification, runtime deprecation logging, scheduled rescans, and v1.2.4 guard/severity/triage accuracy), core functionality is solid and well-tested, but several files have grown past maintainable single-responsibility boundaries.
This document outlines the structural hotspots observed in the v1.2.4 codebase and proposes a phased, behavior-preserving refactor plan.
| File | Lines | Primary Responsibility / Smell |
|---|---|---|
includes/class-thrg-pc-context.php |
1,442 | Combines two distinct static-analysis engines: guard/polyfill context analysis + PHP 8.2+ dynamic property analysis (43 methods). |
includes/view-report.php |
1,154 | Monolithic procedural template mixing layout, navigation, cards, duplicated finding-table markup, runtime logs, history, and email UI. |
assets/checker.css |
1,080 | Single stylesheet covering layout, navigation, cards, opacity tiers, tooltips, modals, and responsive rules. |
includes/trait-thrg-pc-report-methods.php |
1,030 | Trait used solely to split THRG_PHP_Checker; contains evaluate() (348 lines) and component_finding() (367 lines). |
includes/class-thrg-pc-prescan.php |
911 | Pending-update ZIP pre-scanner + WP.org API client (check_wporg_fix() is 204 lines; step() is 151 lines; zip_open() is 78 lines). |
includes/class-thrg-php-checker.php |
788 | Admin controller mixing page bootstrap, AJAX handlers, and admin_post handlers with repeated auth/nonce/redirect boilerplate. |
tests/run.php |
669 | Single procedural test runner (113 assertions). |
includes/class-thrg-pc-email.php |
575 | Email builder + sender (html() is 100 lines, text() is 60 lines). |
includes/class-thrg-pc-runtime-log.php |
543 | Live deprecation hook + debug.log importer (import_debug_log() is 64 lines). |
includes/class-thrg-pc-scanner.php |
540 | Component discovery + time-boxed AJAX scan queue (components() 88 lines, step_locked() 103 lines). |
assets/js/checker.js |
538 | Monolithic admin script (scan polling, expand/collapse drawers, WP.org fix checks, tooltips, email/history interactions). |
- Current State:
THRG_PC_Report_Methods(1,030lines) exists as a PHPtraitmixed intoTHRG_PHP_Checker. Inside it:evaluate()spans 348 lines (L197–L544), handling component sorting, server PHP lifecycle/advisory checks, update-check summaries, and verdict aggregation.component_finding()spans 367 lines (L545–L911), handling finding sorting, fatal vs. non-fatal counts, "What to do" guidance generation, and WP.org badge state.
- Target Design:
THRG_PC_Server_Advisory: EncapsulatePHP_SUPPORT,PHP_ADVISORIES,PATCH_LIST_AS_OF, and server lifecycle/security evaluation.THRG_PC_Evaluator: Dedicated class withevaluate()decomposed into small helpers (build_component_rows(),sort_findings(),build_action_guidance(),summarize_counts()).THRG_PC_Text_Report: Dedicated plain-text formatter (plain_text()).
- Benefit: Eliminates 350-line methods and replaces an artificial trait split with testable, single-purpose classes.
Priority 2 — Split includes/view-report.php (1,154 lines) into Partials & Eliminate Duplicated Table Markup
- Current State:
view-report.phprenders the entire report page in one template and duplicates the finding row<tr>...</tr>rendering across the initial 8-row table (L300–L333) and the overflow drawer (L350+). - Target Design:
- Extract a small row-rendering helper (or partial
includes/partials/finding-row.php) shared by$initial_issues,$overflow_issues, and$guarded_notes. - Split
view-report.phpinto focused partials underincludes/views/:report-nav.php(left urgency navigation + tools/settings tooltips)report-verdict.php(Readiness Verdict banner + summary tiles)report-card.php(component finding card + technical code drawer)report-sections.php(runtime deprecations, update pre-scan, history, email panel)
- Extract a small row-rendering helper (or partial
- Benefit: Cuts template size by ~70% per file and guarantees column/badge consistency across initial and overflow finding tables.
- Current State:
class-thrg-pc-context.phphouses both:- Guard/polyfill token-stream analysis (
guarded(),eval_guard(),collect_dead_branch_vars(), etc.) - PHP 8.2+ dynamic property analysis (
dynamic_property_findings(),104lines;extract_class_info(),126lines)
- Guard/polyfill token-stream analysis (
- Target Design: Move
dynamic_property_findings(),extract_class_info(), and their class/attribute/property helpers intoincludes/class-thrg-pc-dynamic-properties.php(THRG_PC_Dynamic_Properties). - Benefit: Keeps
THRG_PC_Contextfocused purely on version/existence guard evaluation (~1,000 lines -> cleaner scope) and isolates PHP 8.2+ AST/token rules.
- Current State:
check_wporg_fix()(L685–L888) mixes slug normalization, transient cache lookup,wp_remote_get()WP.org API querying, ZIP download, ZIP entry scanning, and response shaping (repeating thestatus/version/verdict/errors/warnings/messagearray structure across early returns). - Target Design:
- Add a
wporg_result( $status, $message, $extra = array() )helper to standardize return payloads. - Split into
resolve_wporg_package(),download_and_scan_zip(), andsummarize_wporg_fix(). - Audit shared file-filtering / PHP-extension checks between
THRG_PC_PrescanandTHRG_PC_Scannerso exclusions and size ceilings live in one helper (THRG_PC_EngineorTHRG_PC_Scanner).
- Add a
- Current State:
ajax_scan_start()(64lines),handle_start_post()(66lines),handle_save_settings()(66lines), andhandle_email_report()(76lines) repeat nonce verification,manage_optionscapability checks, target PHP sanitization, and redirect/JSON error responses. - Target Design: Introduce
verify_admin_post( $action )andverify_ajax_request( $action )helpers to centralize auth/nonce checks and reduce handler length by ~30%.
- Assets: Group
checker.css(1,080lines) with clear section TOCs (or split intolayout.css,cards.css,nav.css) and organizechecker.js(538lines) into small IIFE/module sections (scanController,drawers,wporgCheck,tooltips). - Documentation: Update
PROJECT.mdto reflect currentv1.2.4test assertion counts (113assertions, currently listed as103) and build artifact version (1.2.4, currently listed as1.2.1), and referenceREFACTOR.mdfor contributor architecture guidance.
- Behavior-Preserving Steps: Refactor one module at a time (e.g.,
view-report.phppartials first, thenTHRG_PC_Dynamic_Properties, thenTHRG_PC_Evaluator). - Quality Gates After Every Step:
/usr/local/bin/phpcs --standard=phpcs.xml.dist php tests/run.php
- Preserve Public Contracts: Keep
THRG_PC_Results::for_target(),THRG_PC_Engine::scan_content(),THRG_PC_Context::guarded_lines(), andTHRG_PC_Context::dynamic_property_findings()signatures intact (or provide thin delegating wrappers) sotests/run.phpand WordPress hooks remain backwards-compatible.
- Stage 1 —
view-report.phpModularization: Extractedincludes/views/{report-nav,report-cards,finding-row,report-clean,report-share-schedule,report-tools}.phpand deduplicated finding-row rendering across initial and overflow tables. - Stage 2 — Dynamic Property Extraction: Extracted
THRG_PC_Dynamic_Properties(includes/class-thrg-pc-dynamic-properties.php) fromclass-thrg-pc-context.php, keepingTHRG_PC_Context::dynamic_property_findings()as a backwards-compatible wrapper. - Stage 3 —
THRG_PC_Prescan::check_wporg_fix()Decomposition: Split intowporg_result(),resolve_wporg_package(),scan_wporg_package(), andsummarize_wporg_fix(). - Stage 4 — Controller Capability Helpers: Added
require_admin_ajax()andrequire_admin_post()inincludes/class-thrg-php-checker.phpto deduplicate capability checks across all AJAX andadmin_posthandlers. - Stage 5 — Report Trait Replacement: Replaced
includes/trait-thrg-pc-report-methods.phpwithTHRG_PC_Server_Advisory(includes/class-thrg-pc-server-advisory.php),THRG_PC_Evaluator(includes/class-thrg-pc-evaluator.php), andTHRG_PC_Text_Report(includes/class-thrg-pc-text-report.php), keeping thin delegators onTHRG_PHP_Checker. - Stage 6 —
PROJECT.mdSync & Final Verification: UpdatedPROJECT.mdto reflect the new architecture,32/32PHPCS files,113assertions, and1.2.4build artifacts.