*/ private array $desc_cache = array(); public function __construct( private Options $options ) {} /** * Analyze a post; persists results to post meta and returns them. * * @return array */ /** * Meta whose value the stored analysis depends on. * * Staleness was judged only by post_modified, and writing post meta does * not touch post_modified. So applying an AI title left the checks and both * scores judging the title it replaced: the drawer showed the new text, the * audit went on failing the old one, and nothing the reader did made the * score move. Every key here invalidates the analysis when it changes. * * @var array */ public const SCORED_META = array( '_airanksuite_seo_title', '_airanksuite_seo_desc', '_airanksuite_focus_keyword', '_airanksuite_keywords', '_airanksuite_robots', '_airanksuite_canonical', ); /** Timestamp of the last change to any SCORED_META key. */ public const DIRTY = '_airanksuite_analysis_dirty'; /** Note that the stored analysis no longer describes this page. */ public static function mark_dirty( int $post_id ): void { update_post_meta( $post_id, self::DIRTY, (string) time() ); } /** The moment the analysis stopped being true, or zero. */ private static function dirty_at( int $post_id ): int { return (int) get_post_meta( $post_id, self::DIRTY, true ); } public function analyze( WP_Post $post ): array { $html = Html::rendered( $post ); $words = Html::word_count( $html ); $headings = Html::headings( $html ); $paragraphs = Html::paragraphs( $html ); $all_keywords = KeywordAnalyzer::get( $post->ID ); $keyword = (string) ( $all_keywords['shorttail'][0] ?? '' ); $coverage = ( new KeywordAnalyzer() )->coverage( $post, $html, $all_keywords, $headings, $paragraphs ); $checks = array_merge( $this->seo_checks( $post, $html, $words, $headings ), '' !== $keyword ? $this->keyword_checks( $post, $html, $words, $headings, $paragraphs, $keyword ) : array(), $this->geo_checks( $post, $html, $words, $headings, $paragraphs ), $this->coverage_checks( $coverage ), // The catalogue that names a number and a direction rather than a // verdict. Keyword-dependent ones are skipped entirely when there // is no keyword, because "your keyword is missing from the title" // is noise on a page that has not chosen one yet. Checks::general( $post, $html, $words, $headings, $paragraphs ), Checks::readability( $post, $html ), '' !== $keyword ? Checks::keyword( $post, $html, $words, $headings, $paragraphs, $keyword ) : array() ); // Checks:: supersedes seven of the original checks with versions that // name the number instead of the verdict — "appears 7 times in 4961 // words" rather than "density: weak". Three of them even shared an id // with their replacement, which would have rendered the same row twice // under one React key. Drop the originals here rather than unpick // thirty call sites. $superseded = array( 'kw_in_title', 'kw_in_slug', 'kw_in_intro', 'kw_in_heading', 'kw_density', 'kw_in_alt', 'internal_links', 'external_links', ); $seen = array(); $checks = array_values( array_filter( $checks, static function ( $check ) use ( $superseded, &$seen ) { $id = (string) ( $check['id'] ?? '' ); // A superseded id survives only if it carries a section, // which is the marker of the new catalogue. if ( in_array( $id, $superseded, true ) && ! isset( $check['section'] ) ) { return false; } if ( isset( $seen[ $id ] ) ) { return false; } $seen[ $id ] = true; return true; } ) ); // Everything written before Checks existed has no section. Rather than // touch thirty call sites, they land in the section their scoring group // implies — which is where a reader would look for them anyway. // Where each pre-existing check belongs on screen. Without this they // all landed in "Basics", which then held thirteen rows and meant // nothing — a group everything falls into is not a group. $legacy_sections = array( 'title_length' => 'title', 'meta_description' => 'title', 'kw_in_description' => 'title', 'single_h1' => 'content', 'heading_hierarchy' => 'content', 'word_count' => 'content', 'image_alt' => 'links', 'slug_quality' => 'technical', ); foreach ( $checks as $index => $check ) { if ( ! isset( $check['section'] ) ) { $id = (string) ( $check['id'] ?? '' ); $checks[ $index ]['section'] = $legacy_sections[ $id ] ?? ( 'geo' === ( $check['group'] ?? '' ) ? 'ai' : 'basics' ); } if ( ! isset( $check['ai'] ) ) { $checks[ $index ]['ai'] = false; } } list( $internal_links, $external_links ) = Html::links( $html ); $seo = $this->seo_score_v2( $checks, $keyword ); $result = array( 'post_id' => $post->ID, 'words' => $words, 'keyword' => $keyword, 'keywords' => $all_keywords, 'coverage' => $coverage, 'links' => array( 'internal' => $internal_links, 'external' => $external_links, ), // The numbers behind the readability checks, so the editor can draw // the meter without re-running the analysis. 'readability' => Readability::score( Html::text( $html ), \AiRankSuite\Support\Multilingual::post_language( (int) $post->ID ) ), 'seo_score' => $seo['score'], 'seo_breakdown' => $seo['pillars'], 'geo_score' => $this->score( $checks, 'geo' ), 'checks' => $checks, 'sections' => Checks::sections(), 'analyzed_at' => time(), // The labels below this line are translated text. Storing them // without recording the language they were written in is how a // site that later installs the German translation keeps reading // English checks under a German interface for ever. 'locale' => determine_locale(), 'version' => self::VERSION, ); // This run is now the current answer, so the dirty marker it was // triggered by has been honoured and must not fire again. delete_post_meta( $post->ID, self::DIRTY ); update_post_meta( $post->ID, '_airanksuite_seo_score', $result['seo_score'] ); update_post_meta( $post->ID, '_airanksuite_geo_score', $result['geo_score'] ); /* * And what it scored before. Without this the plugin can only say what * a page is, never what changed about it, so an evening spent on * descriptions leaves no trace anybody can point at. A run that * produces the same two numbers writes nothing. */ ScoreHistory::record( $post->ID, (int) $result['geo_score'], (int) $result['seo_score'] ); /* * Does this page publish a description at all? * * Not "is our own field filled" — that is what the dashboard counted, * and it told a site whose pages all carry a Rank Math description, or * a description template, that 160 pages had none. The analyzer * already resolves the description the way the page actually emits it; * this writes the answer down as one row so a COUNT can read it * instead of loading every post to ask again. */ update_post_meta( $post->ID, self::HAS_DESC, 'none' === $this->description_state( $post )['source'] ? '0' : '1' ); // A column of its own, not a key inside the summary blob: the word-count // distribution is a GROUP BY over this value, and a serialised array // cannot be summed in SQL. update_post_meta( $post->ID, Words::META, $words ); // The seven area scores, each as its own meta row so the dashboard can // average them across the whole site in one query instead of loading // every post to add them up in PHP. \AiRankSuite\Modules\GeoScore\Services\Dimensions::save( $post->ID, \AiRankSuite\Modules\GeoScore\Services\Dimensions::score( $result['checks'] ) ); // Denormalized for the post-list column, which must not decode the full // analysis JSON for every row. update_post_meta( $post->ID, '_airanksuite_summary', array( 'keyword' => $keyword, 'keywords' => array_sum( array_map( 'count', $all_keywords ) ), 'internal' => $internal_links, 'external' => $external_links, 'words' => $words, ) ); // wp_slash: update_post_meta unslashes, which would corrupt JSON escape sequences. update_post_meta( $post->ID, '_airanksuite_analysis', wp_slash( (string) wp_json_encode( $result, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES ) ) ); /** * Fires after a post analysis completes. * * @param array $result The analysis result. * @param WP_Post $post The post. */ do_action( 'airanksuite/content_analyzer/analyzed', $result, $post ); return $result; } /** * Cached analysis (re-runs when post was modified since). * * @return array */ /** * The stored analysis, without ever running one. * * `get()` re-analyses when the stored result is older than the post — which * is right for a single page being opened, and wrong for a list: rendering * twenty-five rows after a bulk edit would run twenty-five full analyses * inside one GET request, each one also writing post meta. A list shows * what is stored and says when it is out of date. * * @return array|null Null when the page has never been analysed. */ public function stored( WP_Post $post ): ?array { $raw = get_post_meta( $post->ID, '_airanksuite_analysis', true ); if ( ! is_string( $raw ) || '' === $raw ) { return null; } $decoded = json_decode( $raw, true ); if ( ! is_array( $decoded ) || ! isset( $decoded['analyzed_at'] ) ) { return null; } $decoded['stale'] = (int) $decoded['analyzed_at'] < (int) get_post_modified_time( 'U', true, $post ) // A meta edit does not move post_modified, so an SEO title applied // from the drawer would otherwise leave this reading "current" // while describing the previous one. // Not strictly-less-than. Both are whole seconds, and an apply that // lands in the same second as the analysis before it would // otherwise compare equal and be missed — which is exactly what // happened the first time this was tested. || (int) $decoded['analyzed_at'] <= self::dirty_at( $post->ID ) || ( $decoded['locale'] ?? '' ) !== determine_locale() || (int) ( $decoded['version'] ?? 0 ) < self::VERSION; return $decoded; } public function get( WP_Post $post ): array { $raw = get_post_meta( $post->ID, '_airanksuite_analysis', true ); if ( is_string( $raw ) && '' !== $raw ) { $stored = json_decode( $raw, true ); if ( is_array( $stored ) && isset( $stored['analyzed_at'] ) && $stored['analyzed_at'] >= (int) get_post_modified_time( 'U', true, $post ) // And not written before the last change to a scored field. // Strictly greater: equal seconds mean the meta was written // after this analysis within the same second. && $stored['analyzed_at'] > self::dirty_at( $post->ID ) // A payload written in another language is as stale as one // written before the last edit — the text in it is wrong now. && ( $stored['locale'] ?? '' ) === determine_locale() // And so is one produced by an older set of rules. && (int) ( $stored['version'] ?? 0 ) >= self::VERSION ) { return $stored; } } return $this->analyze( $post ); } /** @param array> $checks */ private function score( array $checks, string $group ): int { $total = 0; $got = 0; foreach ( $checks as $check ) { if ( $check['group'] !== $group ) { continue; } $total += $check['weight']; if ( 'pass' === $check['status'] ) { $got += $check['weight']; } elseif ( 'warn' === $check['status'] ) { $got += $check['weight'] / 2; } } return $total > 0 ? (int) round( 100 * $got / $total ) : 0; } /** * The SEO score, as a formula a person can check by hand. * * Until now the SEO score was the pass rate of the nine "seo" checks, and * the keyword checks (title, description, URL, first paragraph, heading, * density, image alt) fed no score at all. A page with the keyword nowhere * scored the same as one with it everywhere, which is the opposite of what * the number is for. This is the replacement: four pillars with fixed * points, one hundred in total, each pillar earned in proportion to its * own checks (pass earns the weight, warn half of it). * * Keyword 40 in title, description, URL, first paragraph, a subheading, density, an image alt * Title and description 25 title 30–60 characters, description 80–160 * Structure 20 one H1, heading order, 300+ words, alt texts, compact slug * Links 15 at least one internal link, at least one source * * Without a focus keyword the keyword pillar earns nothing and the score * cannot pass 60: a page that targets nothing cannot be said to target it * well. The breakdown travels with the result so the editor can show the * four numbers next to the total. * * @param array> $checks Every check of this run. * @return array{score: int, pillars: array>} */ private function seo_score_v2( array $checks, string $keyword ): array { $pillars = array( 'keyword' => array( 'label' => __( 'Keyword', 'ai-rank-suite' ), 'max' => 40, 'group' => 'keyword', 'ids' => array() ), 'meta' => array( 'label' => __( 'Title and description', 'ai-rank-suite' ), 'max' => 25, 'group' => '', 'ids' => array( 'title_length', 'meta_description' ) ), 'structure' => array( 'label' => __( 'Structure', 'ai-rank-suite' ), 'max' => 20, 'group' => '', 'ids' => array( 'single_h1', 'heading_hierarchy', 'word_count', 'image_alt', 'slug_quality' ) ), 'links' => array( 'label' => __( 'Links', 'ai-rank-suite' ), 'max' => 15, 'group' => '', 'ids' => array( 'internal_links', 'external_links' ) ), ); $out = array(); $score = 0.0; foreach ( $pillars as $id => $pillar ) { $total = 0; $got = 0.0; foreach ( $checks as $check ) { $mine = '' !== $pillar['group'] ? $pillar['group'] === ( $check['group'] ?? '' ) : in_array( (string) ( $check['id'] ?? '' ), $pillar['ids'], true ); if ( ! $mine ) { continue; } $total += (int) $check['weight']; if ( 'pass' === $check['status'] ) { $got += (int) $check['weight']; } elseif ( 'warn' === $check['status'] ) { $got += (int) $check['weight'] / 2; } } $points = $total > 0 ? $pillar['max'] * $got / $total : 0.0; if ( 'keyword' === $id && '' === trim( $keyword ) ) { $points = 0.0; } $score += $points; $out[] = array( 'id' => $id, 'label' => $pillar['label'], 'points' => (int) round( $points ), 'max' => $pillar['max'], 'note' => 'keyword' === $id && '' === trim( $keyword ) ? __( 'No focus keyword set: this pillar earns nothing until one is.', 'ai-rank-suite' ) : '', ); } return array( 'score' => max( 0, min( 100, (int) round( $score ) ) ), 'pillars' => $out, ); } /** @return array */ private function check( string $id, string $group, string $status, int $weight, string $label, string $fix = '' ): array { return compact( 'id', 'group', 'status', 'weight', 'label', 'fix' ); } /** * The description this page actually publishes, and where it came from. * * This used to read two meta keys and the raw post_excerpt column, which * is not what ships. SeoModule::resolve_description() fills the post-type * template and, failing that, the generated excerpt — so a site whose * descriptions all came from a template was told on every single page * that it had none. The snippet area scored 29 across a site whose * snippets were fine, and the answers area lost three points a page for * a summary that existed. Judge the output, not the input field. * * @return array{text: string, source: string} source: own|ai|generated|none */ private function description_state( WP_Post $post ): array { if ( isset( $this->desc_cache[ $post->ID ] ) ) { return $this->desc_cache[ $post->ID ]; } $source = 'none'; if ( '' !== trim( (string) get_post_meta( $post->ID, '_airanksuite_seo_desc', true ) ) ) { $source = 'own'; } elseif ( '' !== trim( (string) get_post_meta( $post->ID, '_airanksuite_ai_summary', true ) ) ) { $source = 'ai'; } $text = trim( \AiRankSuite\Modules\Seo\SeoModule::resolve_description( $post ) ); if ( '' === $text ) { $source = 'none'; } elseif ( 'none' === $source ) { // Template or generated excerpt: real output, but not written for // this page — worth saying so in the advice. $source = 'generated'; } $state = array( 'text' => $text, 'source' => $source, ); $this->desc_cache[ $post->ID ] = $state; return $state; } /** Kept for the three call sites that only need the text. */ private function effective_description( WP_Post $post ): string { return $this->description_state( $post )['text']; } /** * @param array $headings * @return array> */ private function seo_checks( WP_Post $post, string $html, int $words, array $headings ): array { $checks = array(); $title = \AiRankSuite\Modules\Seo\SeoModule::resolve_title( $post ); $title_len = function_exists( 'mb_strlen' ) ? mb_strlen( $title ) : strlen( $title ); $checks[] = $this->check( 'title_length', 'seo', ( $title_len >= 30 && $title_len <= 60 ) ? 'pass' : ( ( $title_len >= 20 && $title_len <= 70 ) ? 'warn' : 'fail' ), 3, __( 'SEO title length (30–60 characters)', 'ai-rank-suite' ), sprintf( /* translators: %d: characters */ __( 'Current title is %d characters. Aim for 30–60 so it neither truncates nor wastes space.', 'ai-rank-suite' ), $title_len ) ); $desc_state = $this->description_state( $post ); $desc = Html::text( $desc_state['text'] ); $desc_len = function_exists( 'mb_strlen' ) ? mb_strlen( $desc ) : strlen( $desc ); if ( 0 === $desc_len ) { $desc_fix = __( 'This page publishes no description at all. Write one in the editor below, or set a description template for this post type under SEO → Templates so every page gets one.', 'ai-rank-suite' ); } elseif ( 'generated' === $desc_state['source'] ) { $desc_fix = sprintf( /* translators: %d: characters */ __( 'The description is generated (template or excerpt) and is %d characters long. That counts — it is what search engines and assistants read. A sentence written for this page in particular usually earns more clicks.', 'ai-rank-suite' ), $desc_len ); } else { $desc_fix = sprintf( /* translators: %d: characters */ __( 'Current description is %d characters — adjust toward 80–160.', 'ai-rank-suite' ), $desc_len ); } $checks[] = $this->check( 'meta_description', 'seo', ( $desc_len >= 80 && $desc_len <= 160 ) ? 'pass' : ( $desc_len > 0 ? 'warn' : 'fail' ), 3, __( 'Meta description (80–160 characters)', 'ai-rank-suite' ), $desc_fix ); $h1_in_content = count( array_filter( $headings, static fn( $h ) => 1 === $h[0] ) ); $checks[] = $this->check( 'single_h1', 'seo', 0 === $h1_in_content ? 'pass' : 'fail', 2, __( 'Exactly one H1 (the post title)', 'ai-rank-suite' ), __( 'Content contains additional H1 tags — demote them to H2 so the page has one unambiguous topic.', 'ai-rank-suite' ) ); $hierarchy_ok = true; $seen_h2 = false; foreach ( $headings as $h ) { if ( 2 === $h[0] ) { $seen_h2 = true; } if ( 3 === $h[0] && ! $seen_h2 ) { $hierarchy_ok = false; break; } } $checks[] = $this->check( 'heading_hierarchy', 'seo', $hierarchy_ok ? 'pass' : 'warn', 2, __( 'Logical heading hierarchy (H2 before H3)', 'ai-rank-suite' ), __( 'An H3 appears before any H2 — fix the outline so machines can build a clean document tree.', 'ai-rank-suite' ) ); list( $img_total, $img_missing ) = Html::images_alt( $html ); $checks[] = $this->check( 'image_alt', 'seo', 0 === $img_missing ? 'pass' : ( $img_missing < $img_total ? 'warn' : 'fail' ), 2, __( 'All images have alt text', 'ai-rank-suite' ), sprintf( /* translators: 1: missing, 2: total */ __( '%1$d of %2$d images are missing alt text.', 'ai-rank-suite' ), $img_missing, max( 1, $img_total ) ) ); if ( 0 === $img_total ) { $checks[ count( $checks ) - 1 ]['status'] = 'pass'; $checks[ count( $checks ) - 1 ]['fix'] = ''; } list( $internal, $external ) = Html::links( $html ); $checks[] = $this->check( 'internal_links', 'seo', $internal >= 1 ? 'pass' : 'fail', 2, __( 'Links to other pages on this site', 'ai-rank-suite' ), __( 'Add at least one internal link — isolated pages are weak for crawlers and LLMs alike.', 'ai-rank-suite' ) ); $checks[] = $this->check( 'external_links', 'seo', $external >= 1 ? 'pass' : 'warn', 1, __( 'Cites external sources', 'ai-rank-suite' ), __( 'Linking reputable sources increases citation-worthiness for AI answers.', 'ai-rank-suite' ) ); $checks[] = $this->check( 'word_count', 'seo', $words >= 300 ? 'pass' : ( $words >= 150 ? 'warn' : 'fail' ), 2, __( 'Content depth (300+ words)', 'ai-rank-suite' ), sprintf( /* translators: %d: words */ __( 'Currently %d words. Thin pages rarely rank or get cited.', 'ai-rank-suite' ), $words ) ); $slug = (string) $post->post_name; $checks[] = $this->check( 'slug_quality', 'seo', ( strlen( $slug ) > 0 && strlen( $slug ) <= 75 ) ? 'pass' : 'warn', 1, __( 'Readable, compact URL slug', 'ai-rank-suite' ), __( 'Keep slugs short and descriptive.', 'ai-rank-suite' ) ); return $checks; } /** * Focus-keyword checks — only run when the author set a keyword. * * @param array $headings Headings. * @param array $paragraphs Paragraphs. * @return array> */ private function keyword_checks( WP_Post $post, string $html, int $words, array $headings, array $paragraphs, string $keyword ): array { $lower = $this->lower( Html::text( $html ) ); $needle = $this->lower( $keyword ); $checks = array(); $title = \AiRankSuite\Modules\Seo\SeoModule::resolve_title( $post ); $in_title = str_contains( $this->lower( $title ), $needle ); $checks[] = $this->check( 'kw_in_title', 'keyword', $in_title ? 'pass' : 'fail', 3, __( 'Focus keyword appears in the SEO title', 'ai-rank-suite' ), __( 'Put the focus keyword in the title, ideally near the beginning.', 'ai-rank-suite' ) ); $desc = $this->lower( Html::text( $this->effective_description( $post ) ) ); $checks[] = $this->check( 'kw_in_description', 'keyword', str_contains( $desc, $needle ) ? 'pass' : 'warn', 2, __( 'Focus keyword appears in the meta description', 'ai-rank-suite' ), __( 'Mention the keyword once in the description — it is bolded in search results.', 'ai-rank-suite' ) ); $slug = $this->lower( str_replace( '-', ' ', (string) $post->post_name ) ); $checks[] = $this->check( 'kw_in_slug', 'keyword', str_contains( $slug, $needle ) ? 'pass' : 'warn', 2, __( 'Focus keyword appears in the URL', 'ai-rank-suite' ), __( 'A descriptive slug containing the keyword helps both readers and crawlers.', 'ai-rank-suite' ) ); $first = $this->lower( $paragraphs[0] ?? '' ); $checks[] = $this->check( 'kw_in_intro', 'keyword', str_contains( $first, $needle ) ? 'pass' : 'fail', 3, __( 'Focus keyword appears in the first paragraph', 'ai-rank-suite' ), __( 'State the topic immediately — search engines and LLMs weight the opening heavily.', 'ai-rank-suite' ) ); $in_heading = false; foreach ( $headings as $heading ) { if ( $heading[0] >= 2 && str_contains( $this->lower( $heading[1] ), $needle ) ) { $in_heading = true; break; } } $checks[] = $this->check( 'kw_in_heading', 'keyword', $in_heading ? 'pass' : 'warn', 2, __( 'Focus keyword appears in a subheading', 'ai-rank-suite' ), __( 'Use the keyword (or a close variant) in at least one H2 or H3.', 'ai-rank-suite' ) ); $occurrences = $this->count_occurrences( $lower, $needle ); $density = $words > 0 ? ( $occurrences * $this->word_count_of( $needle ) / $words ) * 100 : 0.0; $density_ok = $density >= 0.5 && $density <= 2.5; $checks[] = $this->check( 'kw_density', 'keyword', $density_ok ? 'pass' : ( $density > 0 ? 'warn' : 'fail' ), 2, __( 'Keyword density between 0.5% and 2.5%', 'ai-rank-suite' ), sprintf( /* translators: 1: density percentage, 2: occurrence count */ __( 'Currently %1$s%% (%2$d occurrences). Below 0.5%% reads as off-topic, above 2.5%% as stuffing.', 'ai-rank-suite' ), number_format_i18n( $density, 2 ), $occurrences ) ); $alt_hit = false; if ( preg_match_all( '/alt\s*=\s*("([^"]*)"|\'([^\']*)\')/i', $html, $matches ) ) { foreach ( $matches[2] as $index => $alt ) { $alt = '' !== $alt ? $alt : $matches[3][ $index ]; if ( str_contains( $this->lower( $alt ), $needle ) ) { $alt_hit = true; break; } } } $checks[] = $this->check( 'kw_in_alt', 'keyword', $alt_hit ? 'pass' : 'warn', 1, __( 'Focus keyword appears in an image alt text', 'ai-rank-suite' ), __( 'Describe at least one image using the keyword — it also improves accessibility.', 'ai-rank-suite' ) ); return $checks; } /** * Aggregate checks across all keyword groups. * * @param array $coverage Coverage result. * @return array> */ private function coverage_checks( array $coverage ): array { $checks = array(); $summary = (array) $coverage['summary']; $labels = array( 'shorttail' => __( 'Short-tail keyword coverage', 'ai-rank-suite' ), 'longtail' => __( 'Long-tail keyword coverage', 'ai-rank-suite' ), 'geo' => __( 'GEO prompt coverage', 'ai-rank-suite' ), ); $fixes = array( 'shorttail' => __( 'Some short-tail keywords barely appear. Work them into headings and the opening paragraph.', 'ai-rank-suite' ), 'longtail' => __( 'Long-tail phrases are missing from the text — they are the easiest wins in AI answers.', 'ai-rank-suite' ), 'geo' => __( 'Several prompts have no self-contained answer on this page. Add a section that answers them in 40+ words.', 'ai-rank-suite' ), ); foreach ( array( 'shorttail', 'longtail', 'geo' ) as $group ) { $data = (array) ( $summary[ $group ] ?? array() ); if ( empty( $data['total'] ) ) { continue; } $percent = (int) $data['coverage']; $checks[] = $this->check( 'coverage_' . $group, 'keyword', $percent >= 70 ? 'pass' : ( $percent >= 40 ? 'warn' : 'fail' ), 3, $labels[ $group ], sprintf( /* translators: 1: covered count, 2: total count, 3: percentage */ __( '%1$d of %2$d covered (%3$d%%). %4$s', 'ai-rank-suite' ), (int) $data['covered'], (int) $data['total'], $percent, $percent >= 70 ? '' : $fixes[ $group ] ) ); } return $checks; } private function lower( string $value ): string { return function_exists( 'mb_strtolower' ) ? mb_strtolower( $value, 'UTF-8' ) : strtolower( $value ); } private function count_occurrences( string $haystack, string $needle ): int { return '' === $needle ? 0 : (int) substr_count( $haystack, $needle ); } private function word_count_of( string $value ): int { return max( 1, count( preg_split( '/\s+/u', trim( $value ) ) ?: array() ) ); } /** * @param array $headings * @param array $paragraphs * @return array> */ private function geo_checks( WP_Post $post, string $html, int $words, array $headings, array $paragraphs ): array { $checks = array(); $first = $paragraphs[0] ?? ''; $first_wc = '' === $first ? 0 : count( preg_split( '/\s+/u', $first ) ?: array() ); $checks[] = $this->check( 'answer_first', 'geo', $first_wc >= 40 ? 'pass' : ( $first_wc >= 20 ? 'warn' : 'fail' ), 3, __( 'Opening paragraph answers the topic (40+ words)', 'ai-rank-suite' ), __( 'LLMs weight the opening heavily. Start with a self-contained answer, not a warm-up.', 'ai-rank-suite' ) ); $desc = Html::text( $this->effective_description( $post ) ); $checks[] = $this->check( 'summary_present', 'geo', '' !== $desc ? 'pass' : 'fail', 3, __( 'Summary/excerpt exists', 'ai-rank-suite' ), __( 'This is the sentence that represents the page in llms.txt and in an assistant\'s answer. A description template covers the whole site at once; the AI writer can write one per page.', 'ai-rank-suite' ) ); $h2plus = count( array_filter( $headings, static fn( $h ) => $h[0] >= 2 ) ); $needed = $words > 600 ? max( 1, (int) floor( $words / 300 ) ) : ( $words > 300 ? 1 : 0 ); $checks[] = $this->check( 'chunkable_headings', 'geo', $h2plus >= $needed ? 'pass' : ( $h2plus > 0 ? 'warn' : ( 0 === $needed ? 'pass' : 'fail' ) ), 3, __( 'Enough subheadings for chunking (~1 per 300 words)', 'ai-rank-suite' ), sprintf( /* translators: 1: found 2: recommended */ __( '%1$d subheadings found, ~%2$d recommended. LLMs chunk along headings.', 'ai-rank-suite' ), $h2plus, max( 1, $needed ) ) ); $has_lists = (bool) preg_match( '/<(ul|ol|table)\b/i', $html ); $checks[] = $this->check( 'lists_tables', 'geo', $has_lists ? 'pass' : 'warn', 1, __( 'Uses lists or tables', 'ai-rank-suite' ), __( 'Structured facts (lists, tables) are extracted and cited more reliably than prose.', 'ai-rank-suite' ) ); $question = count( array_filter( $headings, static fn( $h ) => str_ends_with( trim( $h[1] ), '?' ) ) ); $checks[] = $this->check( 'question_headings', 'geo', $question >= 1 ? 'pass' : 'warn', 1, __( 'At least one question-style heading', 'ai-rank-suite' ), __( 'Question headings map directly onto the prompts people ask AI assistants.', 'ai-rank-suite' ) ); $long_paras = count( array_filter( $paragraphs, static fn( $p ) => count( preg_split( '/\s+/u', $p ) ?: array() ) > 120 ) ); $checks[] = $this->check( 'paragraph_brevity', 'geo', 0 === $long_paras ? 'pass' : ( $long_paras <= 2 ? 'warn' : 'fail' ), 2, __( 'Paragraphs stay digestible (≤120 words)', 'ai-rank-suite' ), sprintf( /* translators: %d: count */ __( '%d paragraphs exceed 120 words — split them for cleaner chunking.', 'ai-rank-suite' ), $long_paras ) ); $llms = $this->options->get( 'llms_txt', Generator::defaults() ); $included = ! get_post_meta( $post->ID, '_airanksuite_exclude', true ) && in_array( $post->post_type, (array) $llms['post_types'], true ) && ! empty( $llms['enabled'] ); $checks[] = $this->check( 'llms_included', 'geo', $included ? 'pass' : 'warn', 2, __( 'Included in llms.txt', 'ai-rank-suite' ), __( 'This page is not part of your llms.txt — AI crawlers may miss it.', 'ai-rank-suite' ) ); return $checks; } }