25, 'warning' => 10, 'info' => 2, // R3 (audit_issues). 'high' => 18, 'medium' => 10, 'low' => 5, 'notice' => 2, ); /** * Content score at/below which the gap starts counting, and how much * each missing point adds. Mirrors the poor/ok boundary used by * ABDS_SEO_Content_Analyzer::categorize_score() rather than inventing * a second idea of "bad enough to act on". */ const CONTENT_SCORE_FLOOR = 60; const CONTENT_GAP_WEIGHT = 0.5; /** * Weight of a confident downward decay trend. Multiplied by the * detector's R² confidence, so a noisy "maybe declining" contributes * proportionally less than a clean slide. */ const DECAY_WEIGHT = 30; /** * Added when a page has never been analyzed: unknown is a small nudge * to look, not evidence of a problem. */ const NOT_ANALYZED_WEIGHT = 5; /** * Upper bound of the traffic multiplier. A page with real traffic is * worth at most twice a page with none — never more, or a popular page * with one cosmetic nit would outrank a broken page with modest * traffic. */ const MAX_TRAFFIC_MULTIPLIER = 2.0; /** * Clicks producing the maximum multiplier. Growth is logarithmic: the * step from 0 to 100 clicks/month matters far more than 5000 to 10000, * so traffic tilts the ranking without dominating it. */ const TRAFFIC_SATURATION = 10000; /** * Scores one page. Note that technical_score is deliberately NOT an * input: it is itself derived from the same issues list, so counting * both would weigh every technical problem twice. * * @param array $page { * Page signals. * * @type array $issues Issues from the scanner: {code, severity, message}. * @type ?int $content_score Content score 0-100, or null if never analyzed. * @type string $decay_trend Decay trend slug, e.g. 'declining'. * @type float $decay_confidence Decay R², 0-1. * @type ?int $traffic Clicks over the traffic window, or null if unknown. * } * @return array{score:int, problem_score:int, traffic_multiplier:float, reasons:array} */ public static function score_page( array $page ): array { $reasons = array(); $problem_score = 0.0; foreach ( self::count_severities( (array) ( $page['issues'] ?? array() ) ) as $severity => $count ) { $weight = self::SEVERITY_WEIGHTS[ $severity ] * $count; $problem_score += $weight; $reasons[] = array( 'code' => 'issues_' . $severity, 'weight' => (int) round( $weight ), 'count' => $count, ); } $content_score = $page['content_score'] ?? null; if ( null === $content_score ) { $problem_score += self::NOT_ANALYZED_WEIGHT; $reasons[] = array( 'code' => 'not_analyzed', 'weight' => self::NOT_ANALYZED_WEIGHT, 'count' => 0, ); } elseif ( (int) $content_score < self::CONTENT_SCORE_FLOOR ) { $weight = ( self::CONTENT_SCORE_FLOOR - (int) $content_score ) * self::CONTENT_GAP_WEIGHT; $problem_score += $weight; $reasons[] = array( 'code' => 'low_content_score', 'weight' => (int) round( $weight ), 'count' => (int) $content_score, ); } if ( 'declining' === ( $page['decay_trend'] ?? '' ) ) { $confidence = min( 1.0, max( 0.0, (float) ( $page['decay_confidence'] ?? 0 ) ) ); $weight = self::DECAY_WEIGHT * $confidence; $problem_score += $weight; $reasons[] = array( 'code' => 'declining', 'weight' => (int) round( $weight ), 'count' => 0, ); } $problem_score = min( 100.0, $problem_score ); $multiplier = self::traffic_multiplier( $page['traffic'] ?? null ); usort( $reasons, fn( $a, $b ) => $b['weight'] <=> $a['weight'] ); return array( 'score' => (int) round( min( 100.0, $problem_score * $multiplier ) ), 'problem_score' => (int) round( $problem_score ), 'traffic_multiplier' => round( $multiplier, 2 ), 'reasons' => $reasons, ); } /** * Scores every page and returns them ordered worst-first, dropping the * ones with nothing wrong — an attention list must not be padded with * healthy pages. * * @param array $pages List of page signal arrays (see score_page()), each with a 'post_id'. * @param int $limit Max rows to return; 0 = no limit. * @return array Scored pages, highest priority first. */ public static function rank( array $pages, int $limit = 0 ): array { $scored = array(); foreach ( $pages as $page ) { $result = self::score_page( $page ); if ( $result['problem_score'] <= 0 ) { continue; } $scored[] = array_merge( $page, $result ); } // Ties break on traffic, then post_id — without the post_id the // order of equally-scored pages would wobble between requests and // the "top 5" in the email would not match the dashboard. usort( $scored, function ( $a, $b ) { return array( $b['score'], (int) ( $b['traffic'] ?? 0 ), (int) ( $a['post_id'] ?? 0 ) ) <=> array( $a['score'], (int) ( $a['traffic'] ?? 0 ), (int) ( $b['post_id'] ?? 0 ) ); } ); return $limit > 0 ? array_slice( $scored, 0, $limit ) : $scored; } /** * Traffic weighting: 1.0 with no traffic (or no GSC connection at all, * where traffic is null for every page and the ranking falls back to * pure severity), scaling logarithmically up to MAX_TRAFFIC_MULTIPLIER. * * @param ?int $traffic Clicks, or null if unknown. * @return float Multiplier between 1.0 and MAX_TRAFFIC_MULTIPLIER. */ public static function traffic_multiplier( ?int $traffic ): float { if ( null === $traffic || $traffic <= 0 ) { return 1.0; } $ratio = log10( 1 + min( $traffic, self::TRAFFIC_SATURATION ) ) / log10( 1 + self::TRAFFIC_SATURATION ); return 1.0 + ( self::MAX_TRAFFIC_MULTIPLIER - 1.0 ) * $ratio; } /** * Reads a stored wp_abds_seo_page_scores.issues_json blob into a * scanner-shaped issues list. * * Two different writers share that column: ABDS_SEO_Site_Scanner stores * a flat list of {code, severity, message}, while * ABDS_SEO_Content_Analyzer stores {"content_recommendations": [...]} * — whichever ran last wins. Only the scanner's shape carries * severities, so anything else yields no technical issues instead of * being coerced into a severity it never had. * * @param ?string $blob Raw issues_json value. * @return array */ public static function issues_from_blob( ?string $blob ): array { $decoded = json_decode( (string) $blob, true ); if ( ! is_array( $decoded ) ) { return array(); } $issues = array(); foreach ( $decoded as $key => $entry ) { // A string key means the content-analyzer shape, not a list. if ( ! is_int( $key ) || ! is_array( $entry ) || ! isset( $entry['severity'] ) ) { continue; } $issues[] = array( 'code' => (string) ( $entry['code'] ?? '' ), 'severity' => (string) $entry['severity'], 'message' => (string) ( $entry['message'] ?? '' ), ); } return $issues; } /** * Normalizes a set of wp_abds_seo_audit_issues rows (as fetched by * ABDS_SEO_Priority_Service, which owns the actual query — this class * stays pure/WP-free per its own docblock) into the same * {code, severity, message} shape issues_from_blob() produces, so * score_page() and count_severities() don't need to know which source a * page's issues came from. * * @param array $rows Raw audit_issues rows for one page. * @return array */ public static function issues_from_audit_rows( array $rows ): array { return array_map( function ( $row ): array { return array( 'code' => (string) $row->issue_key, 'severity' => (string) $row->severity, 'message' => (string) ( $row->message ?? '' ), ); }, $rows ); } /** * Counts issues per known severity, ignoring unknown severities rather * than guessing a weight for them. * * @param array $issues Issues from the scanner. * @return array Count keyed by severity, only non-zero entries. */ protected static function count_severities( array $issues ): array { $counts = array(); foreach ( $issues as $issue ) { $severity = (string) ( $issue['severity'] ?? '' ); if ( ! isset( self::SEVERITY_WEIGHTS[ $severity ] ) ) { continue; } $counts[ $severity ] = ( $counts[ $severity ] ?? 0 ) + 1; } return $counts; } /** * Human-readable label for a reason code. Kept apart from scoring so * the scorer stays locale-independent and testable on codes, while the * dashboard and the digest share one set of wordings. * * @param array $reason Reason entry from score_page(). * @return string Translated label. */ public static function reason_label( array $reason ): string { $count = (int) ( $reason['count'] ?? 0 ); switch ( (string) ( $reason['code'] ?? '' ) ) { case 'issues_critical': /* translators: %d: number of critical issues. */ return sprintf( _n( 'Critical error: %d', 'Critical errors: %d', $count, 'abds-seo' ), $count ); case 'issues_warning': /* translators: %d: number of warnings. */ return sprintf( _n( 'Warning: %d', 'Warnings: %d', $count, 'abds-seo' ), $count ); case 'issues_info': /* translators: %d: number of minor notes. */ return sprintf( _n( 'Minor note: %d', 'Minor notes: %d', $count, 'abds-seo' ), $count ); case 'issues_high': /* translators: %d: number of high-severity issues. */ return sprintf( _n( 'High-severity issue: %d', 'High-severity issues: %d', $count, 'abds-seo' ), $count ); case 'issues_medium': /* translators: %d: number of medium-severity issues. */ return sprintf( _n( 'Medium-severity issue: %d', 'Medium-severity issues: %d', $count, 'abds-seo' ), $count ); case 'issues_low': /* translators: %d: number of low-severity issues. */ return sprintf( _n( 'Low-severity issue: %d', 'Low-severity issues: %d', $count, 'abds-seo' ), $count ); case 'issues_notice': /* translators: %d: number of notices. */ return sprintf( _n( 'Notice: %d', 'Notices: %d', $count, 'abds-seo' ), $count ); case 'low_content_score': /* translators: %d: content score, 0-100. */ return sprintf( __( 'Low content score: %d', 'abds-seo' ), $count ); case 'declining': return __( 'Sustained drop in traffic/positions', 'abds-seo' ); case 'not_analyzed': return __( 'The page has not been analyzed yet', 'abds-seo' ); default: return ''; } } }