*/ public function calculate(): array { $checks = array_merge( $this->discovery_checks(), $this->structure_checks(), $this->answers_checks(), $this->schema_checks() ); $dimensions = array(); foreach ( array( 'discovery', 'structure', 'answers', 'schema' ) as $dim ) { $dim_checks = array_values( array_filter( $checks, static fn( $c ) => $c['dimension'] === $dim ) ); $dimensions[ $dim ] = $this->score_of( $dim_checks ); } /** * Filter the weight each dimension carries in the overall AI score — a schema-heavy agency can make Schema count double. * * @param array $weights discovery / structure / answers / schema => relative weight. */ $weights = (array) apply_filters( 'airanksuite/geo_score/weights', array( 'discovery' => 1, 'structure' => 1, 'answers' => 1, 'schema' => 1, ) ); $weighted = 0.0; $divisor = 0.0; foreach ( $dimensions as $dim => $score ) { $w = max( 0.0, (float) ( $weights[ $dim ] ?? 1 ) ); $weighted += $score * $w; $divisor += $w; } $dimensions['overall'] = (int) round( $weighted / max( 1e-6, $divisor ) ); $result = array( 'dimensions' => $dimensions, 'checks' => $checks, 'calculated_at' => time(), ); update_option( 'airanksuite_geo_score_latest', $result, false ); // The history the dashboard sparkline and the analyzer trend read. // It was read in two places and written in none, so the site score // never had a past. Keep one point for every explicit recalculation; // that is the action and granularity promised by the dashboard copy. // The bounded list prevents repeated checks from growing the option // without limit. $history = get_option( 'airanksuite_geo_score_history', array() ); $history = is_array( $history ) ? $history : array(); $last = end( $history ); $point = array( 'day' => gmdate( 'Y-m-d' ), 'time' => time(), 'value' => (int) $dimensions['overall'], ); $history[] = $point; update_option( 'airanksuite_geo_score_history', array_values( array_slice( $history, -180 ) ), false ); // A manual recalculation is expected to update the mounted dashboard // immediately. Without invalidating both aggregate payloads, the REST // requests that follow can return the previous values for 5–10 minutes. delete_transient( 'airanksuite_dashboard_trends' ); delete_transient( 'airanksuite_kpis' ); \AiRankSuite\Support\Events::emit( 'score.recalculated', array( 'overall' => (int) $dimensions['overall'], 'previous' => is_array( $last ) ? (int) ( $last['value'] ?? 0 ) : null, 'dimensions' => $dimensions, ) ); return $result; } /** * Latest cached result or fresh calculation. * * @return array */ public function latest(): array { $stored = get_option( 'airanksuite_geo_score_latest' ); return is_array( $stored ) ? $stored : $this->calculate(); } /** * Weighted score 0-100 for a set of checks (warn counts half). * * @param array> $checks Checks. */ private function score_of( array $checks ): int { $total = 0; $got = 0; foreach ( $checks as $check ) { $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; } /** * Build one check row. * * @param string $id Check id. * @param string $dimension Dimension key. * @param string $status pass|warn|fail. * @param int $weight Weight. * @param string $label Human label. * @param string $fix Fix hint. * @return array */ private function check( string $id, string $dimension, string $status, int $weight, string $label, string $fix = '' ): array { return compact( 'id', 'dimension', 'status', 'weight', 'label', 'fix' ); } /** @return array> */ private function discovery_checks(): array { $checks = array(); $llms_enabled = ! empty( $this->options->get( 'llms_txt', Generator::defaults() )['enabled'] ); $checks[] = $this->check( 'llms_txt_enabled', 'discovery', $llms_enabled ? 'pass' : 'fail', 3, __( 'llms.txt is enabled', 'ai-rank-suite' ), __( 'Enable the llms.txt generator so AI crawlers get a curated map of your site.', 'ai-rank-suite' ) ); $checks[] = $this->check( 'pretty_permalinks', 'discovery', get_option( 'permalink_structure' ) ? 'pass' : 'fail', 2, __( 'Readable URLs (pretty permalinks)', 'ai-rank-suite' ), __( 'Enable pretty permalinks in Settings → Permalinks; query-string URLs are weak signals for AI crawlers.', 'ai-rank-suite' ) ); $blog_public = (bool) get_option( 'blog_public' ); $checks[] = $this->check( 'site_indexable', 'discovery', $blog_public ? 'pass' : 'fail', 3, __( 'Site allows indexing', 'ai-rank-suite' ), __( 'Your site discourages search engines (Settings → Reading) — AI crawlers respect this and skip you.', 'ai-rank-suite' ) ); $sitemap = function_exists( 'wp_sitemaps_get_server' ); $checks[] = $this->check( 'sitemap_present', 'discovery', $sitemap ? 'pass' : 'warn', 2, __( 'XML sitemap available', 'ai-rank-suite' ), __( 'Expose an XML sitemap so crawlers can enumerate your content.', 'ai-rank-suite' ) ); return $checks; } /** @return array> */ private function structure_checks(): array { $posts = $this->sample_posts(); $total = count( $posts ); $with_headings = 0; $long_enough = 0; foreach ( $posts as $post ) { if ( preg_match( '/]/i', (string) $post->post_content ) ) { ++$with_headings; } if ( str_word_count( wp_strip_all_tags( (string) $post->post_content ) ) >= 300 ) { ++$long_enough; } } return array( $this->check( 'headings_usage', 'structure', $this->ratio_status( $with_headings, $total, 0.7, 0.4 ), 3, __( 'Content uses subheadings (H2–H4)', 'ai-rank-suite' ), __( 'LLMs chunk content along headings — add descriptive subheadings to long posts.', 'ai-rank-suite' ) ), $this->check( 'content_depth', 'structure', $this->ratio_status( $long_enough, $total, 0.6, 0.3 ), 2, __( 'Content depth (300+ words)', 'ai-rank-suite' ), __( 'Thin pages rarely get cited; expand key pages into self-contained references.', 'ai-rank-suite' ) ), ); } /** @return array> */ private function answers_checks(): array { $posts = $this->sample_posts(); $total = count( $posts ); $with_excerpt = 0; foreach ( $posts as $post ) { if ( '' !== trim( (string) $post->post_excerpt ) || '' !== (string) get_post_meta( $post->ID, '_airanksuite_ai_summary', true ) ) { ++$with_excerpt; } } return array( $this->check( 'summaries_coverage', 'answers', $this->ratio_status( $with_excerpt, $total, 0.7, 0.3 ), 3, __( 'Pages have summaries/excerpts', 'ai-rank-suite' ), __( 'Excerpts become the descriptions in llms.txt and help LLMs ground answers — AI summary generation automates this in v1.', 'ai-rank-suite' ) ), $this->check( 'tagline_set', 'answers', '' !== trim( (string) get_bloginfo( 'description' ) ) ? 'pass' : 'warn', 1, __( 'Site tagline describes the site', 'ai-rank-suite' ), __( 'Set a descriptive tagline (Settings → General) — it is the one-line answer to "what is this site?".', 'ai-rank-suite' ) ), ); } /** @return array> */ private function schema_checks(): array { $seo_schema = defined( 'WPSEO_VERSION' ) || class_exists( 'RankMath' ) || defined( 'AIOSEO_VERSION' ); return array( $this->check( 'schema_source', 'schema', $seo_schema ? 'pass' : 'warn', 2, __( 'Structured data (JSON-LD) source detected', 'ai-rank-suite' ), __( 'No schema source detected — the Schema Generator module (v1.1) will emit an entity-grounded JSON-LD graph.', 'ai-rank-suite' ) ), ); } /** * Sample of recent published posts/pages for content checks. * * @return array */ private function sample_posts(): array { return get_posts( array( 'post_type' => array( 'post', 'page' ), 'post_status' => 'publish', 'posts_per_page' => 50, 'orderby' => 'date', 'order' => 'DESC', ) ); } /** * pass/warn/fail from a coverage ratio. * * @param int $hit Matching items. * @param int $total Total items. * @param float $pass Pass threshold. * @param float $warn Warn threshold. */ private function ratio_status( int $hit, int $total, float $pass, float $warn ): string { if ( 0 === $total ) { return 'warn'; } $ratio = $hit / $total; if ( $ratio >= $pass ) { return 'pass'; } return $ratio >= $warn ? 'warn' : 'fail'; } }