> */ public static function sections(): array { return array( array( 'id' => 'essentials', 'label' => __( 'Essentials', 'ai-rank-suite' ), 'note' => __( 'If any of these is wrong, nothing further matters much.', 'ai-rank-suite' ), ), array( 'id' => 'content', 'label' => __( 'The content itself', 'ai-rank-suite' ), 'note' => __( 'Length, structure and whether the page answers its own question early.', 'ai-rank-suite' ), ), array( 'id' => 'machine', 'label' => __( 'Machine readability', 'ai-rank-suite' ), 'note' => __( 'What an assistant can state as fact rather than infer from prose.', 'ai-rank-suite' ), ), array( 'id' => 'sharing', 'label' => __( 'Sharing & previews', 'ai-rank-suite' ), 'note' => __( 'What a link to this page looks like everywhere it gets pasted.', 'ai-rank-suite' ), ), array( 'id' => 'technical', 'label' => __( 'Technical', 'ai-rank-suite' ), 'note' => __( 'Crawling, indexing, images and the things that break silently.', 'ai-rank-suite' ), ), array( 'id' => 'links', 'label' => __( 'Links', 'ai-rank-suite' ), 'note' => __( 'How this page connects to the rest of the site and beyond it.', 'ai-rank-suite' ), ), ); } /** * The whole report for one post. * * @return array */ public static function build( WP_Post $post ): array { $html = Html::rendered( $post ); $text = Html::text( $html ); $words = Html::word_count( $html ); $headings = Html::headings( $html ); $paragraphs = Html::paragraphs( $html ); $images = Html::images_alt( $html ); $links = Html::links( $html ); $head = HeadMeta::plan( $post ); $tags = array(); foreach ( $head['tags'] as $tag ) { $tags[ (string) $tag['key'] ] = $tag; } $tag = static fn( string $key ): string => (string) ( $tags[ $key ]['value'] ?? '' ); $keywords = KeywordAnalyzer::get( $post->ID ); $focus = (string) ( $keywords['shorttail'][0] ?? '' ); $h1 = array_values( array_filter( $headings, static fn( $h ) => 1 === (int) ( $h[0] ?? 0 ) ) ); $h2 = array_values( array_filter( $headings, static fn( $h ) => 2 === (int) ( $h[0] ?? 0 ) ) ); $internal = 0; $external = 0; $home = wp_parse_url( home_url( '/' ), PHP_URL_HOST ); foreach ( $links as $link ) { $href = is_array( $link ) ? (string) ( $link['href'] ?? '' ) : (string) $link; if ( '' === $href || str_starts_with( $href, '#' ) ) { continue; } $host = wp_parse_url( $href, PHP_URL_HOST ); if ( null === $host || $host === $home ) { ++$internal; } else { ++$external; } } $missing_alt = 0; foreach ( $images as $image ) { $alt = is_array( $image ) ? (string) ( $image['alt'] ?? '' ) : (string) $image; if ( '' === trim( $alt ) ) { ++$missing_alt; } } $title = $tag( 'title' ); $desc = $tag( 'name:description' ); $title_n = self::len( $title ); $desc_n = self::len( $desc ); $robots = $tag( 'name:robots' ); $faqs = \AiRankSuite\Support\StoredReads::faq_items( $post->ID ); $excluded = (bool) get_post_meta( $post->ID, '_airanksuite_exclude', true ); $opening = (string) ( $paragraphs[0] ?? '' ); $r = array(); // ── Essentials ────────────────────────────────────────────────────── $r[] = self::item( 'title', 'essentials', 5, '' !== $title && $title_n >= 25 && $title_n <= 60, __( 'The title is present and fits', 'ai-rank-suite' ), '' === $title ? __( 'There is no title at all.', 'ai-rank-suite' ) : sprintf( /* translators: %d: character count. */ __( '%d characters. Google truncates around 60; under 25 rarely fits both a subject and a reason to click.', 'ai-rank-suite' ), $title_n ), $title ); $r[] = self::item( 'description', 'essentials', 5, '' !== $desc && $desc_n >= 80 && $desc_n <= 160, __( 'The meta description is written and fits', 'ai-rank-suite' ), '' === $desc ? __( 'Search engines will write one from your first paragraph, whatever that happens to be.', 'ai-rank-suite' ) : sprintf( /* translators: %d: character count. */ __( '%d characters. Aim for 80–160.', 'ai-rank-suite' ), $desc_n ), $desc ); $r[] = self::item( 'h1', 'essentials', 4, 1 === count( $h1 ), __( 'Exactly one H1', 'ai-rank-suite' ), 0 === count( $h1 ) ? __( 'No H1. The page has no stated subject in its own markup.', 'ai-rank-suite' ) : sprintf( /* translators: %d: number of H1s. */ __( '%d H1 headings. More than one and the subject is ambiguous.', 'ai-rank-suite' ), count( $h1 ) ) ); $r[] = self::item( 'indexable', 'essentials', 5, ! str_contains( $robots, 'noindex' ), __( 'The page may be indexed', 'ai-rank-suite' ), str_contains( $robots, 'noindex' ) ? __( 'This page is set to noindex, so it cannot appear in results at all.', 'ai-rank-suite' ) : __( 'No noindex directive.', 'ai-rank-suite' ), $robots ); $r[] = self::item( 'canonical', 'essentials', 3, '' !== $tag( 'rel:canonical' ), __( 'A canonical URL is declared', 'ai-rank-suite' ), __( 'Names the one address that should be indexed when the page is reachable more than one way.', 'ai-rank-suite' ), $tag( 'rel:canonical' ) ); // ── Content ───────────────────────────────────────────────────────── $r[] = self::item( 'length', 'content', 4, $words >= 300, __( 'Enough text to answer something', 'ai-rank-suite' ), sprintf( /* translators: 1: word count, 2: reading time. */ __( '%1$d words, about %2$s to read. Under 300 a page is rarely quoted, because there is not enough of it to quote.', 'ai-rank-suite' ), $words, sprintf( /* translators: %d: number of minutes. */ _n( '%d minute', '%d minutes', Words::minutes( $words ), 'ai-rank-suite' ), Words::minutes( $words ) ) ), (string) $words ); $r[] = self::item( 'structure', 'content', 3, count( $h2 ) >= 2 || $words < 300, __( 'Broken into sections', 'ai-rank-suite' ), sprintf( /* translators: %d: number of H2 headings. */ __( '%d H2 headings. Sub-headings are the unit an assistant quotes — a wall of text has no quotable part.', 'ai-rank-suite' ), count( $h2 ) ) ); $r[] = self::item( 'opening', 'content', 4, self::len( $opening ) >= 40, __( 'The opening paragraph answers the question', 'ai-rank-suite' ), '' === $opening ? __( 'The page has no opening paragraph.', 'ai-rank-suite' ) : __( 'The first paragraph is what gets extracted. A one-line lead-in wastes the most valuable place on the page.', 'ai-rank-suite' ), mb_substr( $opening, 0, 160 ) ); $r[] = self::item( 'keyword', 'content', 3, '' !== $focus, __( 'A focus keyword is set', 'ai-rank-suite' ), '' === $focus ? __( 'Without one, nothing can check whether the page is about what you meant it to be about.', 'ai-rank-suite' ) : sprintf( /* translators: %s: the keyword. */ __( 'Focus keyword: %s', 'ai-rank-suite' ), $focus ), $focus ); if ( '' !== $focus ) { $in_title = false !== mb_stripos( $title, $focus ); $in_opening = false !== mb_stripos( $opening, $focus ); $r[] = self::item( 'keyword_title', 'content', 3, $in_title, __( 'The keyword is in the title', 'ai-rank-suite' ), __( 'Not for the ranking, for the match: a result whose title does not contain the query reads as the wrong answer.', 'ai-rank-suite' ) ); $r[] = self::item( 'keyword_opening', 'content', 2, $in_opening, __( 'The keyword appears in the opening', 'ai-rank-suite' ), __( 'Confirms in the first sentences that the reader is in the right place.', 'ai-rank-suite' ) ); } // ── Machine readability ───────────────────────────────────────────── $r[] = self::item( 'schema', 'machine', 4, '' !== $tag( 'application/ld+json' ), __( 'Structured data is present', 'ai-rank-suite' ), __( 'The only part of the page that states its facts in a form a machine cannot misread.', 'ai-rank-suite' ) ); $r[] = self::item( 'faq', 'machine', 2, count( $faqs ) > 0, __( 'Question and answer pairs', 'ai-rank-suite' ), sprintf( /* translators: %d: number of FAQ items. */ __( '%d saved. Q&A is the single most quotable format for an assistant, because the question is the query.', 'ai-rank-suite' ), count( $faqs ) ) ); $r[] = self::item( 'llms', 'machine', 2, ! $excluded, __( 'Listed in llms.txt', 'ai-rank-suite' ), $excluded ? __( 'This page is excluded from the machine-readable index AI crawlers read first.', 'ai-rank-suite' ) : __( 'Included in the index AI crawlers read before they crawl anything.', 'ai-rank-suite' ) ); $r[] = self::item( 'summary', 'machine', 2, '' !== trim( (string) get_post_meta( $post->ID, '_airanksuite_ai_summary', true ) ), __( 'An AI summary is stored', 'ai-rank-suite' ), __( 'A paragraph written to be repeated, rather than a meta description written to fit a 155-character snippet.', 'ai-rank-suite' ) ); // ── Sharing ───────────────────────────────────────────────────────── $r[] = self::item( 'og_image', 'sharing', 3, '' !== $tag( 'property:og:image' ), __( 'A share image', 'ai-rank-suite' ), __( 'Without one every link to this page renders as a grey box on LinkedIn, WhatsApp and Slack.', 'ai-rank-suite' ) ); $r[] = self::item( 'og_title', 'sharing', 2, '' !== $tag( 'property:og:title' ), __( 'An Open Graph title', 'ai-rank-suite' ), __( 'The headline in the link preview. It may differ from the SEO title — a share is read by a person.', 'ai-rank-suite' ) ); $r[] = self::item( 'tw_card', 'sharing', 1, '' !== $tag( 'name:twitter:card' ), __( 'A Twitter card type', 'ai-rank-suite' ), __( 'summary_large_image gets the full-width picture; without it X falls back to a thumbnail.', 'ai-rank-suite' ) ); // ── Technical ─────────────────────────────────────────────────────── $r[] = self::item( 'alt', 'technical', 3, 0 === $missing_alt, __( 'Every image has alt text', 'ai-rank-suite' ), 0 === $missing_alt ? sprintf( /* translators: %d: number of images. */ _n( '%d image, described.', '%d images, all described.', count( $images ), 'ai-rank-suite' ), count( $images ) ) : sprintf( /* translators: 1: images without alt, 2: total images. */ __( '%1$d of %2$d images have no alt text. That is an accessibility failure before it is an SEO one.', 'ai-rank-suite' ), $missing_alt, count( $images ) ) ); $r[] = self::item( 'snippet_limit', 'technical', 3, ! str_contains( $robots, 'nosnippet' ), __( 'Snippets are allowed', 'ai-rank-suite' ), str_contains( $robots, 'nosnippet' ) ? __( 'nosnippet stops AI answers quoting this page at all — the most effective way to be invisible in generative results.', 'ai-rank-suite' ) : __( 'max-snippet:-1 lets an answer quote the page at length.', 'ai-rank-suite' ) ); $r[] = self::item( 'slug', 'technical', 2, '' !== $post->post_name && mb_strlen( $post->post_name ) <= 75 && ! preg_match( '/^\d+$/', $post->post_name ), __( 'A readable URL', 'ai-rank-suite' ), __( 'The slug appears in the result, in shares and in citations. A number tells nobody anything.', 'ai-rank-suite' ), $post->post_name ); $r[] = self::item( 'published', 'technical', 2, 'publish' === $post->post_status, __( 'Published', 'ai-rank-suite' ), 'publish' === $post->post_status ? __( 'Live and crawlable.', 'ai-rank-suite' ) : sprintf( /* translators: %s: post status. */ __( 'Status is “%s”, so none of this is on the internet yet.', 'ai-rank-suite' ), $post->post_status ) ); // ── Links ─────────────────────────────────────────────────────────── $r[] = self::item( 'internal_out', 'links', 3, $internal >= 2, __( 'Links out to the rest of the site', 'ai-rank-suite' ), sprintf( /* translators: %d: number of internal links. */ __( '%d internal links. A page with none is a dead end for a crawler and for a reader.', 'ai-rank-suite' ), $internal ), (string) $internal ); $r[] = self::item( 'external_out', 'links', 1, $external >= 1, __( 'Cites something outside the site', 'ai-rank-suite' ), sprintf( /* translators: %d: number of external links. */ __( '%d external links. Citing sources is a signal of a real article rather than filler.', 'ai-rank-suite' ), $external ) ); // Incoming links come from the link graph if that module has built one. $incoming = self::incoming( $post->ID ); if ( null !== $incoming ) { $r[] = self::item( 'internal_in', 'links', 3, $incoming >= 1, __( 'Other pages link to it', 'ai-rank-suite' ), 0 === $incoming ? __( 'Nothing on the site links here, so it is an orphan — reachable only from the sitemap.', 'ai-rank-suite' ) : sprintf( /* translators: %d: number of incoming links. */ __( '%d internal links point here.', 'ai-rank-suite' ), $incoming ), (string) $incoming ); } // ── Score ─────────────────────────────────────────────────────────── $earned = 0; $possible = 0; $counts = array( 'pass' => 0, 'fail' => 0 ); foreach ( $r as $item ) { $possible += (int) $item['weight']; if ( $item['pass'] ) { $earned += (int) $item['weight']; ++$counts['pass']; } else { ++$counts['fail']; } } return array( 'sections' => self::sections(), 'items' => $r, 'score' => $possible > 0 ? (int) round( ( $earned / $possible ) * 100 ) : 0, 'earned' => $earned, 'possible' => $possible, 'passed' => $counts['pass'], 'failed' => $counts['fail'], 'words' => $words, 'reading' => Words::minutes( $words ), 'band' => Words::band( $words ), 'images' => count( $images ), 'internal' => $internal, 'external' => $external, 'headings' => count( $headings ), /* * What this page scored the first time it was looked at, against * what it scores now. Null until there are two readings: with one * there is a score and no story, and "+0 since today" is worse * than saying nothing. */ 'change' => ScoreHistory::change( $post->ID ), ); } /** * How many internal links point at this post, if the link graph knows. * * Returns null rather than 0 when the graph has never been built: "no page * links here" and "we have not looked" are different answers, and only one * of them is a problem. */ private static function incoming( int $post_id ): ?int { global $wpdb; $table = \AiRankSuite\Support\Database::found_links(); // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery $exists = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table ) ); if ( $table !== $exists ) { return null; } // Nothing crawled yet means "we have not looked", which is a different // answer from "nothing links here" and must not be reported as one. // The run scope is a literal in both statements; with no published // scan its flag is 0 and nothing matches. $scope = \AiRankSuite\Support\StoredReads::linkscan_scope(); $any = (int) $wpdb->get_var( $wpdb->prepare( 'SELECT COUNT(*) FROM %i WHERE ( %d = 1 AND run_id = %s )', $table, $scope[0], $scope[1] ) ); if ( 0 === $any ) { return null; } // The table stores the href as written, so the same page appears with // and without a trailing slash and under either scheme. Hashing all // four forms is cheaper and more accurate than a LIKE over a TEXT // column, which could not use the index anyway. $permalink = (string) get_permalink( $post_id ); $variants = array_unique( array( $permalink, untrailingslashit( $permalink ), trailingslashit( $permalink ), str_replace( 'https://', 'http://', $permalink ), ) ); $hashes = array_map( 'md5', $variants ); $ph = implode( ', ', array_fill( 0, count( $hashes ), '%s' ) ); return (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(DISTINCT post_id) FROM %i WHERE ( %d = 1 AND run_id = %s ) AND internal = 1 AND url_hash IN ( {$ph} ) AND post_id <> %d", array_merge( array( $table, $scope[0], $scope[1] ), $hashes, array( $post_id ) ) ) ); // phpcs:enable } /** * @return array */ private static function item( string $id, string $section, int $weight, bool $pass, string $label, string $detail, string $value = '' ): array { return array( 'id' => $id, 'section' => $section, 'weight' => $weight, 'pass' => $pass, 'label' => $label, 'detail' => $detail, 'value' => $value, ); } private static function len( string $value ): int { return function_exists( 'mb_strlen' ) ? mb_strlen( $value ) : strlen( $value ); } }