*/ public static function columns(): array { return array( array( 'key' => 'snippet', 'label' => __( 'Title & description', 'ai-rank-suite' ), 'hint' => __( 'The two lines Google and ChatGPT show before anyone clicks', 'ai-rank-suite' ), 'fix' => __( 'The result people read before they decide. Fix it in bulk from the Content screen — titles and descriptions are the fastest sitewide win there is.', 'ai-rank-suite' ), ), array( 'key' => 'content', 'label' => __( 'Content', 'ai-rank-suite' ), 'hint' => __( 'Whether there is enough on the page, and whether it reads easily', 'ai-rank-suite' ), 'fix' => __( 'Usually a length problem. The Length tab shows the distribution and names the shortest pages.', 'ai-rank-suite' ), ), array( 'key' => 'structure', 'label' => __( 'Structure', 'ai-rank-suite' ), 'hint' => __( 'Subheadings and lists — the pieces an assistant lifts out and quotes', 'ai-rank-suite' ), 'fix' => __( 'Sub-headings are the unit an assistant quotes. A cold column here usually means one template that renders no H2s.', 'ai-rank-suite' ), ), array( 'key' => 'answers', 'label' => __( 'Answers', 'ai-rank-suite' ), 'hint' => __( 'Whether the page answers the question in its first lines instead of warming up', 'ai-rank-suite' ), 'fix' => __( 'The single biggest lever for being cited rather than merely ranked. The autopilot can write summaries for the whole site.', 'ai-rank-suite' ), ), array( 'key' => 'keywords', 'label' => __( 'Search terms', 'ai-rank-suite' ), 'hint' => __( 'Whether a page has a term it is meant to be found for — and uses it', 'ai-rank-suite' ), 'fix' => __( 'A cold column here often just means nobody has set focus keywords yet, not that the writing is wrong.', 'ai-rank-suite' ), ), array( 'key' => 'links', 'label' => __( 'Links', 'ai-rank-suite' ), 'hint' => __( 'Links to your own other pages, and to sources elsewhere', 'ai-rank-suite' ), 'fix' => __( 'Internal links are the cheapest ranking change on any site. The Links screen suggests them per page.', 'ai-rank-suite' ), ), array( 'key' => 'media', 'label' => __( 'Images', 'ai-rank-suite' ), 'hint' => __( 'Alt text — the sentence that describes a picture to search engines and screen readers', 'ai-rank-suite' ), 'fix' => __( 'An accessibility failure before it is an SEO one, and one the AI can fix in bulk.', 'ai-rank-suite' ), ), ); } /** * Which area a check belongs to — named after the thing an editor would * open to fix it, not after our internal scoring group. */ public static function area( string $id, string $group ): string { $map = array( 'seo_title' => 'snippet', 'meta_description' => 'snippet', 'slug_quality' => 'snippet', 'kw_in_title' => 'snippet', 'kw_in_description' => 'snippet', 'kw_in_slug' => 'snippet', 'word_count' => 'content', 'paragraph_brevity' => 'content', 'heading_hierarchy' => 'structure', 'chunkable_headings' => 'structure', 'question_headings' => 'structure', 'lists_tables' => 'structure', 'answer_first' => 'answers', 'summary_present' => 'answers', 'llms_included' => 'answers', 'internal_links' => 'links', 'external_links' => 'links', 'image_alt' => 'media', 'kw_in_alt' => 'media', ); if ( isset( $map[ $id ] ) ) { return $map[ $id ]; } if ( str_starts_with( $id, 'kw_' ) || str_starts_with( $id, 'coverage_' ) ) { return 'keywords'; } return 'geo' === $group ? 'answers' : 'content'; } /** * Roll a page's checks up into the seven areas. * * @param array> $checks Analysis checks. * @return array area => 0..100 */ public static function score( array $checks ): array { $buckets = array(); foreach ( $checks as $check ) { $area = self::area( (string) $check['id'], (string) ( $check['group'] ?? 'seo' ) ); if ( ! isset( $buckets[ $area ] ) ) { $buckets[ $area ] = array( 'earned' => 0.0, 'possible' => 0.0 ); } $weight = max( 1, (int) ( $check['weight'] ?? 1 ) ); $earned = 'pass' === $check['status'] ? $weight : ( 'warn' === $check['status'] ? $weight / 2 : 0 ); $buckets[ $area ]['earned'] += $earned; $buckets[ $area ]['possible'] += $weight; } $out = array(); foreach ( $buckets as $area => $b ) { if ( $b['possible'] > 0 ) { $out[ $area ] = (int) round( 100 * $b['earned'] / $b['possible'] ); } } return $out; } /** * Store the area scores as individual meta rows. * * Individually, not as one serialised array, precisely so they can be * averaged in SQL. A serialised blob would put us straight back to loading * every post in PHP to compute a site average. * * @param array $scores Area scores. */ public static function save( int $post_id, array $scores ): void { foreach ( self::columns() as $column ) { $key = self::PREFIX . $column['key']; if ( isset( $scores[ $column['key'] ] ) ) { update_post_meta( $post_id, $key, (int) $scores[ $column['key'] ] ); } else { // A page with no checks in an area has no score in it, and a // stale value from a previous analysis would be worse than none. delete_post_meta( $post_id, $key ); } } } /** * Site-wide roll-up: one query, every analyzed page. * * @return array> */ public static function board(): array { global $wpdb; $keys = array_map( static fn( array $c ): string => self::PREFIX . $c['key'], self::columns() ); $ph = implode( ', ', array_fill( 0, count( $keys ), '%s' ) ); // Published pages of the eligible types (Support\Inventory) — the same // population as "Pages scored" on the dashboard, so an area's page // count can never exceed the site's. Templates and drafts carry // scores of their own but are not the site's number. $types = \AiRankSuite\Support\Inventory::eligible_types(); if ( empty( $types ) ) { return array_map( static fn( array $c ): array => $c + array( 'pages' => 0, 'average' => null, 'critical' => 0, 'weak' => 0, 'good' => 0 ), self::columns() ); } $tph = implode( ', ', array_fill( 0, count( $types ), '%s' ) ); // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery $rows = $wpdb->get_results( $wpdb->prepare( "SELECT m.meta_key AS k, COUNT(*) AS pages, AVG(m.meta_value + 0) AS avg_score, SUM(m.meta_value + 0 < 40) AS critical, SUM(m.meta_value + 0 BETWEEN 40 AND 69) AS weak, SUM(m.meta_value + 0 >= 70) AS good FROM {$wpdb->postmeta} m INNER JOIN {$wpdb->posts} p ON p.ID = m.post_id WHERE m.meta_key IN ( {$ph} ) AND p.post_type IN ( {$tph} ) AND p.post_status = 'publish' GROUP BY m.meta_key", array_merge( $keys, $types ) ), ARRAY_A ); // phpcs:enable $by = array(); foreach ( (array) $rows as $row ) { $by[ (string) $row['k'] ] = $row; } $out = array(); foreach ( self::columns() as $column ) { $row = $by[ self::PREFIX . $column['key'] ] ?? array(); $pages = (int) ( $row['pages'] ?? 0 ); $out[] = $column + array( 'pages' => $pages, 'average' => isset( $row['avg_score'] ) ? (int) round( (float) $row['avg_score'] ) : null, 'critical' => (int) ( $row['critical'] ?? 0 ), 'weak' => (int) ( $row['weak'] ?? 0 ), 'good' => (int) ( $row['good'] ?? 0 ), ); } return $out; } /** * The worst pages in one area — the drill-down from a cold column. * * @return array> */ public static function worst( string $area, int $limit = 20 ): array { $valid = array_column( self::columns(), 'key' ); if ( ! in_array( $area, $valid, true ) ) { return array(); } global $wpdb; // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery $rows = $wpdb->get_results( $wpdb->prepare( "SELECT p.ID, p.post_title, p.post_type, m.meta_value + 0 AS score FROM {$wpdb->postmeta} m INNER JOIN {$wpdb->posts} p ON p.ID = m.post_id WHERE m.meta_key = %s AND p.post_status IN ( 'publish', 'draft', 'pending', 'future', 'private' ) ORDER BY score ASC LIMIT %d", self::PREFIX . $area, $limit ), ARRAY_A ); // phpcs:enable return array_map( static fn( array $r ): array => array( 'id' => (int) $r['ID'], 'title' => (string) $r['post_title'], 'type' => (string) $r['post_type'], 'score' => (int) $r['score'], ), (array) $rows ); } }