findings = $findings; } /** * @return list */ public function ids(): array { return self::IDS; } /** * @param list,http_status:int|null,content_class:string,error_code:string|null}> $snapshot Shared masked crawl rows. * @return array */ public function analyze( string $check_id, array $snapshot, string $timestamp ): array { if ( ! in_array( $check_id, self::IDS, true ) ) { throw new InvalidArgumentException( 'snapshot_analyzer_unavailable' ); } switch ( $check_id ) { case 'seo.discovery_indexability': return $this->indexability( $snapshot, $timestamp ); case 'seo.robots_sitemaps': return $this->robots_sitemaps( $snapshot, $timestamp ); case 'seo.canonical_hreflang': return $this->canonical_hreflang( $snapshot, $timestamp ); case 'seo.status_redirects': return $this->status_redirects( $snapshot, $timestamp ); case 'seo.metadata_headings': return $this->metadata_headings( $snapshot, $timestamp ); case 'seo.structured_data': return $this->structured_data( $snapshot, $timestamp ); case 'seo.internal_links': return $this->internal_links( $snapshot, $timestamp ); case 'seo.media': return $this->media( $snapshot, $timestamp ); case 'seo.templates_content': return $this->templates_content( $snapshot, $timestamp ); case 'seo.normalization': return $this->normalization( $snapshot, $timestamp ); case 'seo.error_pages': return $this->error_pages( $snapshot, $timestamp ); case 'aeo.answer_structure': return $this->answer_structure( $snapshot, $timestamp ); case 'geo.entity_clarity': return $this->entity_clarity( $snapshot, $timestamp ); case 'geo.provenance_freshness': return $this->provenance_freshness( $snapshot, $timestamp ); case 'geo.publisher_controls': return $this->publisher_controls( $snapshot, $timestamp ); default: return $this->emerging_files( $snapshot, $timestamp ); } } /** * @param list> $snapshot Masked snapshot. * @return array */ private function indexability( array $snapshot, string $timestamp ): array { $pages = $this->page_rows( $snapshot ); $html = $this->html_rows( $pages ); $blocked = array_values( array_filter( $html, static function ( array $row ): bool { $directives = $row['signals']['robots']['directives'] ?? array(); return is_array( $directives ) && ( in_array( 'noindex', $directives, true ) || in_array( 'none', $directives, true ) ); } ) ); $status = array() === $html ? 'not_tested' : ( array() === $blocked ? 'pass' : 'warning' ); return $this->crawl_finding( 'seo.discovery_indexability', $status, array() !== $blocked ? $blocked : $html, count( $html ), count( $pages ), $timestamp, array( 'meta_and_http_only', 'search_inclusion_not_tested' ), array(), array( 'issue_groups' => array() === $blocked ? array() : array( $this->issue_group( 'noindex', $blocked ) ) ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function robots_sitemaps( array $snapshot, string $timestamp ): array { $rows = array_values( array_filter( $snapshot, static fn ( array $row ): bool => in_array( $row['resource_class'] ?? '', array( 'robots', 'sitemap' ), true ) ) ); $robots = array_values( array_filter( $rows, static fn ( array $row ): bool => 'robots' === $row['resource_class'] ) ); $sitemaps = array_values( array_filter( $rows, static fn ( array $row ): bool => 'sitemap' === $row['resource_class'] ) ); $issues = array_values( array_filter( $rows, static function ( array $row ): bool { $state = $row['signals']['state'] ?? ''; $status = (int) ( $row['http_status'] ?? 0 ); return in_array( $state, array( 'not_tested', 'temporarily_unavailable' ), true ) || true === ( $row['signals']['truncated'] ?? false ) || $status >= 500; } ) ); $valid_sitemaps = array_values( array_filter( $sitemaps, static fn ( array $row ): bool => (int) ( $row['http_status'] ?? 0 ) >= 200 && (int) ( $row['http_status'] ?? 0 ) < 300 && 'observed' === ( $row['signals']['state'] ?? '' ) ) ); $observed = array_values( array_filter( $rows, static function ( array $row ): bool { $state = $row['signals']['state'] ?? ''; $status = (int) ( $row['http_status'] ?? 0 ); return 'observed' === ( $row['state'] ?? '' ) && $status >= 100 && $status <= 599 && in_array( $state, array( 'observed', 'parsed', 'unavailable' ), true ); } ) ); $status = array() === $robots ? 'not_tested' : ( array() !== $issues ? 'warning' : ( array() !== $valid_sitemaps ? 'pass' : 'info' ) ); $robots_issues = array_values( array_filter( $issues, static fn ( array $row ): bool => 'robots' === ( $row['resource_class'] ?? '' ) ) ); $sitemap_issues = array_values( array_filter( $issues, static fn ( array $row ): bool => 'sitemap' === ( $row['resource_class'] ?? '' ) ) ); return $this->crawl_finding( 'seo.robots_sitemaps', $status, array() !== $issues ? $issues : $rows, count( $observed ), count( $rows ), $timestamp, array( 'declarations_and_parseability_only', 'search_discovery_not_tested' ), array(), array( 'issue_groups' => $this->issue_groups( array( 'robots_unavailable' => $robots_issues, 'sitemap_unavailable' => $sitemap_issues, ) ), ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function canonical_hreflang( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $issues = array(); $groups = array( 'canonical_multiple' => array(), 'canonical_invalid' => array(), 'canonical_external' => array(), 'canonical_missing' => array(), 'hreflang_invalid' => array(), ); $missing = 0; foreach ( $html as $row ) { $canonical = $row['signals']['canonical'] ?? array(); $hreflang = $row['signals']['hreflang'] ?? array(); if ( 0 === (int) ( $canonical['count'] ?? 0 ) ) { ++$missing; $groups['canonical_missing'][] = $row; } $has_issue = false; foreach ( array( 'canonical_multiple' => (int) ( $canonical['count'] ?? 0 ) > 1, 'canonical_invalid' => (int) ( $canonical['invalid'] ?? 0 ) > 0, 'canonical_external' => (int) ( $canonical['external'] ?? 0 ) > 0, 'hreflang_invalid' => (int) ( $hreflang['invalid'] ?? 0 ) > 0, ) as $code => $matches ) { if ( $matches ) { $groups[ $code ][] = $row; $has_issue = true; } } if ( $has_issue ) { $issues[] = $row; } } $status = array() === $html ? 'not_tested' : ( array() !== $issues ? 'warning' : ( $missing > 0 ? 'info' : 'pass' ) ); return $this->crawl_finding( 'seo.canonical_hreflang', $status, array() !== $issues ? $issues : $html, count( $html ), count( $this->page_rows( $snapshot ) ), $timestamp, array( 'canonical_is_a_hint', 'reciprocity_not_tested' ), array(), array( 'issue_groups' => $this->issue_groups( $groups ) ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function status_redirects( array $snapshot, string $timestamp ): array { $pages = $this->page_rows( $snapshot ); $observed = array_values( array_filter( $pages, static fn ( array $row ): bool => 'observed' === ( $row['state'] ?? '' ) && (int) ( $row['http_status'] ?? 0 ) >= 100 && (int) ( $row['http_status'] ?? 0 ) <= 599 ) ); $server = array_values( array_filter( $observed, static fn ( array $row ): bool => (int) $row['http_status'] >= 500 ) ); $client = array_values( array_filter( $observed, static fn ( array $row ): bool => (int) $row['http_status'] >= 400 && (int) $row['http_status'] < 500 ) ); $redirects = array_values( array_filter( $observed, static fn ( array $row ): bool => (int) $row['http_status'] >= 300 && (int) $row['http_status'] < 400 ) ); $status = array() === $observed ? 'not_tested' : ( array() !== $server ? 'fail' : ( array() !== $client ? 'warning' : ( array() !== $redirects ? 'info' : 'pass' ) ) ); $affected = array() !== $server ? $server : ( array() !== $client ? $client : ( array() !== $redirects ? $redirects : $observed ) ); return $this->crawl_finding( 'seo.status_redirects', $status, $affected, count( $observed ), count( $pages ), $timestamp, array( 'queryless_get_observations_only', 'redirects_may_be_intentional' ), array(), array( 'status_counts' => $this->status_counts( $observed ), 'issue_groups' => $this->issue_groups( array( 'server_error' => $server, 'client_error' => $client, 'redirect' => $redirects, ) ), ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function metadata_headings( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $issues = array(); $groups = array( 'title_missing' => array(), 'title_multiple' => array(), 'description_missing' => array(), 'h1_missing' => array(), 'h1_multiple' => array(), 'heading_empty' => array(), 'heading_level_skip' => array(), ); $descriptions = 0; foreach ( $html as $row ) { $title = $row['signals']['title'] ?? array(); $description = $row['signals']['meta_description'] ?? array(); $headings = $row['signals']['headings'] ?? array(); $h1 = is_array( $headings['counts'] ?? null ) ? (int) ( $headings['counts']['h1'] ?? 0 ) : 0; $descriptions += (int) ( $description['count'] ?? 0 ) > 0 ? 1 : 0; $title_count = (int) ( $title['count'] ?? 0 ); if ( 0 === $title_count ) { $groups['title_missing'][] = $row; } elseif ( $title_count > 1 ) { $groups['title_multiple'][] = $row; } if ( 0 === (int) ( $description['count'] ?? 0 ) ) { $groups['description_missing'][] = $row; } if ( 0 === $h1 ) { $groups['h1_missing'][] = $row; } elseif ( $h1 > 1 ) { $groups['h1_multiple'][] = $row; } if ( (int) ( $headings['empty'] ?? 0 ) > 0 ) { $groups['heading_empty'][] = $row; } if ( (int) ( $headings['level_skips'] ?? 0 ) > 0 ) { $groups['heading_level_skip'][] = $row; } if ( 1 !== $title_count || 1 !== $h1 || (int) ( $headings['empty'] ?? 0 ) > 0 || (int) ( $headings['level_skips'] ?? 0 ) > 0 ) { $issues[] = $row; } } $status = array() === $html ? 'not_tested' : ( array() !== $issues ? 'warning' : ( $descriptions < count( $html ) ? 'info' : 'pass' ) ); $affected = array() !== $issues ? $issues : ( $descriptions < count( $html ) ? $groups['description_missing'] : $html ); return $this->crawl_finding( 'seo.metadata_headings', $status, $affected, count( $html ), count( $this->page_rows( $snapshot ) ), $timestamp, array( 'lengths_are_observations_not_ranking_thresholds', 'rendered_dom_not_tested' ), array(), array( 'issue_groups' => $this->issue_groups( $groups ) ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function structured_data( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $types = array(); $entities = array(); $blocks = 0; $parsed = 0; $errors = 0; $truncated = false; $issue_rows = array(); foreach ( $html as $row ) { $data = $row['signals']['structured_data'] ?? array(); $blocks += (int) ( $data['blocks'] ?? 0 ); $parsed += (int) ( $data['parsed'] ?? 0 ); $errors += (int) ( $data['errors'] ?? 0 ); $truncated = $truncated || true === ( $data['truncated'] ?? false ); if ( (int) ( $data['errors'] ?? 0 ) > 0 || true === ( $data['truncated'] ?? false ) ) { $issue_rows[] = $row; } if ( is_array( $data['types'] ?? null ) ) { $types = array_merge( $types, $data['types'] ); } if ( is_array( $data['entity_references'] ?? null ) ) { $entities = array_merge( $entities, $data['entity_references'] ); } } $types = array_values( array_unique( array_filter( $types, 'is_string' ) ) ); $entities = array_values( array_unique( array_filter( $entities, 'is_string' ) ) ); $status = array() === $html ? 'not_tested' : ( $errors > 0 || $truncated ? 'warning' : ( $parsed > 0 ? 'pass' : 'info' ) ); return $this->findings->build( 'seo.structured_data', $status, array( 'types' => $types, 'parse_results' => array( 'blocks' => $blocks, 'parsed' => $parsed, 'errors' => $errors, 'truncated' => $truncated, ), 'entity_ids' => array_slice( $entities, 0, self::REFERENCE_LIMIT ), 'issue_groups' => array() === $issue_rows ? array() : array( $this->issue_group( 'structured_data_error', $issue_rows ) ), 'limitations' => array( 'schema_validation_not_performed', 'rich_result_eligibility_not_tested' ), ), count( $html ), count( $this->page_rows( $snapshot ) ), $this->coverage( count( $html ), count( $this->page_rows( $snapshot ) ) ), $timestamp, array() === $issue_rows ? array() : $this->affected( $issue_rows ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function internal_links( array $snapshot, string $timestamp ): array { $pages = $this->page_rows( $snapshot ); $html = $this->html_rows( $pages ); $edges = 0; $depth = 0; $targets = array(); $failed = array(); $truncated = false; foreach ( $pages as $row ) { if ( (int) ( $row['http_status'] ?? 0 ) >= 400 || 'error' === ( $row['state'] ?? '' ) ) { $failed[ (string) $row['url_hash'] ] = true; } } foreach ( $html as $row ) { $links = $row['signals']['links'] ?? array(); $edges += (int) ( $links['same_origin'] ?? 0 ); $depth = max( $depth, (int) ( $row['depth'] ?? 0 ) ); $truncated = $truncated || true === ( $links['truncated'] ?? false ); if ( is_array( $links['same_origin_references'] ?? null ) ) { $targets = array_merge( $targets, $links['same_origin_references'] ); } } $broken = array_values( array_intersect( array_unique( array_filter( $targets, 'is_string' ) ), array_keys( $failed ) ) ); $status = array() === $html ? 'not_tested' : ( array() !== $broken ? 'warning' : ( count( $html ) > 1 && 0 === $edges ? 'info' : 'pass' ) ); $broken_rows = $this->rows_by_references( $pages, $broken ); return $this->findings->build( 'seo.internal_links', $status, array( 'nodes' => $this->references( $html ), 'edges' => $edges, 'broken' => array_slice( $broken, 0, self::REFERENCE_LIMIT ), 'depth' => $depth, 'orphans' => 'not_tested', 'truncated' => $truncated || count( $html ) > self::REFERENCE_LIMIT, 'issue_groups' => array() === $broken_rows ? array() : array( $this->issue_group( 'broken_internal_target', $broken_rows ) ), 'limitations' => array( 'queryless_graph_only', 'orphan_detection_requires_content_inventory' ), ), count( $html ), count( $pages ), $this->coverage( count( $html ), count( $pages ) ), $timestamp, $this->affected_by_references( $broken, $pages ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function media( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $images = 0; $missing = 0; $empty = 0; $dimensions = 0; $lazy = 0; $missing_rows = array(); $dimension_rows = array(); foreach ( $html as $row ) { $media = $row['signals']['media'] ?? array(); $images += (int) ( $media['images'] ?? 0 ); $missing += (int) ( $media['missing_alt'] ?? 0 ); $empty += (int) ( $media['empty_alt'] ?? 0 ); $dimensions += (int) ( $media['missing_dimensions'] ?? 0 ); $lazy += (int) ( $media['lazy'] ?? 0 ); if ( (int) ( $media['missing_alt'] ?? 0 ) > 0 ) { $missing_rows[] = $row; } if ( (int) ( $media['missing_dimensions'] ?? 0 ) > 0 ) { $dimension_rows[] = $row; } } $status = array() === $html ? 'not_tested' : ( $missing > 0 ? 'warning' : ( $dimensions > 0 ? 'info' : 'pass' ) ); return $this->findings->build( 'seo.media', $status, array( 'objects' => array( 'images' => $images, 'missing_alt' => $missing, 'empty_alt' => $empty, 'missing_dimensions' => $dimensions, 'lazy' => $lazy, ), 'observed_count' => $images, 'total_count' => $images, 'truncated' => false, 'issue_groups' => $this->issue_groups( array( 'image_alt_missing' => $missing_rows, 'image_dimensions_missing' => $dimension_rows, ) ), 'limitations' => array( 'empty_alt_may_be_intentional', 'image_content_not_assessed' ), ), count( $html ), count( $this->page_rows( $snapshot ) ), $this->coverage( count( $html ), count( $this->page_rows( $snapshot ) ) ), $timestamp, $this->affected( array_merge( $missing_rows, $dimension_rows ) ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function templates_content( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $clusters = array(); foreach ( $html as $row ) { $reference = $row['signals']['title']['reference'] ?? ''; if ( is_string( $reference ) && '' !== $reference ) { $clusters[ $reference ][] = $row; } } $duplicates = array_filter( $clusters, static fn ( array $rows ): bool => count( $rows ) > 1 ); $status = count( $html ) < 2 ? 'not_tested' : ( array() !== $duplicates ? 'warning' : 'pass' ); $duplicate_rows = array(); $groups = array(); foreach ( array_values( $duplicates ) as $index => $rows ) { $duplicate_rows = array_merge( $duplicate_rows, $rows ); $groups[] = $this->issue_group( 'duplicate_title', $rows, $index + 1 ); } return $this->crawl_finding( 'seo.templates_content', $status, array() === $duplicate_rows ? $html : $duplicate_rows, count( $html ), count( $this->page_rows( $snapshot ) ), $timestamp, array( 'hashed_title_cluster_heuristic', 'content_similarity_not_tested' ), array(), array( 'issue_groups' => $groups ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function normalization( array $snapshot, string $timestamp ): array { $kinds = array( 'norm_query', 'norm_slash', 'norm_case', 'norm_protocol' ); $objects = array(); $observed = 0; $issues = 0; foreach ( $kinds as $kind ) { $rows = $this->resource_rows( $snapshot, $kind ); $statuses = array_values( array_filter( array_map( static fn ( array $row ): int => (int) ( $row['http_status'] ?? 0 ), $rows ) ) ); $redirects = count( array_filter( $statuses, static fn ( int $status ): bool => $status >= 300 && $status < 400 ) ); $terminal = array_values( array_filter( $statuses, static fn ( int $status ): bool => $status < 300 || $status >= 400 ) ); $canonical = 0; $parent = 0; foreach ( $rows as $row ) { $canonical += (int) ( $row['signals']['canonical_count'] ?? 0 ); $parent += (int) ( $row['signals']['canonical_parent'] ?? 0 ); $parent += ! empty( $row['signals']['target_is_parent'] ) ? 1 : 0; } if ( array() === $rows ) { $result = 'not_available'; } elseif ( array() === $statuses ) { $result = 'not_tested'; } elseif ( array_filter( $statuses, static fn ( int $status ): bool => $status >= 400 ) ) { $result = 'unexpected_status'; ++$issues; ++$observed; } elseif ( $redirects > 0 && $parent > 0 ) { $result = 'redirected_to_primary'; ++$observed; } elseif ( array_filter( $terminal, static fn ( int $status ): bool => $status >= 200 && $status < 300 ) && $canonical > 0 && $parent > 0 ) { $result = 'canonical_to_primary'; ++$observed; } else { $result = 'duplicate_or_unclear'; ++$issues; ++$observed; } $objects[] = array( 'variant' => $kind, 'result' => $result, 'requests' => count( $rows ), 'redirects' => $redirects, 'canonical_parent' => $parent > 0, ); } $status = 0 === $observed ? 'not_tested' : ( $issues > 0 ? 'warning' : 'pass' ); return $this->findings->build( 'seo.normalization', $status, array( 'objects' => $objects, 'observed_count' => $observed, 'total_count' => count( $kinds ), 'truncated' => false, 'limitations' => array( 'four_bounded_synthetic_gets', 'response_text_not_retained', 'canonical_is_a_hint' ), ), $observed, count( $kinds ), $this->coverage( $observed, count( $kinds ) ), $timestamp ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function error_pages( array $snapshot, string $timestamp ): array { $probes = $this->resource_rows( $snapshot, 'error_probe' ); $natural = array_values( array_filter( $this->page_rows( $snapshot ), static fn ( array $row ): bool => 404 === (int) ( $row['http_status'] ?? 0 ) || 410 === (int) ( $row['http_status'] ?? 0 ) ) ); $statuses = array_values( array_filter( array_map( static fn ( array $row ): int => (int) ( $row['http_status'] ?? 0 ), $probes ) ) ); $redirects = count( array_filter( $statuses, static fn ( int $code ): bool => $code >= 300 && $code < 400 ) ); $expected = array_values( array_filter( $probes, static fn ( array $row ): bool => in_array( (int) ( $row['http_status'] ?? 0 ), array( 404, 410 ), true ) ) ); $template = array_values( array_filter( $expected, static fn ( array $row ): bool => ! empty( $row['signals']['title_present'] ) && (int) ( $row['signals']['h1_count'] ?? 0 ) > 0 && (int) ( $row['signals']['internal_links'] ?? 0 ) > 0 ) ); if ( array() === $probes || array() === $statuses ) { $status = 'not_tested'; } elseif ( $redirects > 0 || array_filter( $statuses, static fn ( int $code ): bool => 200 === $code || $code >= 500 ) ) { $status = 'fail'; } elseif ( array() === $expected ) { $status = 'warning'; } elseif ( array() === $template ) { $status = 'warning'; } else { $status = 'pass'; } return $this->findings->build( 'seo.error_pages', $status, array( 'objects' => array( 'probe_statuses' => $this->status_counts( $probes ), 'natural_error_pages' => count( $natural ), 'redirects' => $redirects, 'valid_error_statuses' => count( $expected ), 'usable_templates' => count( $template ), ), 'observed_count' => array() === $statuses ? 0 : 1, 'total_count' => 1, 'truncated' => false, 'limitations' => array( 'one_random_same_origin_get', 'basic_template_structure_only', 'response_text_not_retained' ), ), array() === $statuses ? 0 : 1, 1, array() === $statuses ? 'none' : 'complete', $timestamp, $this->affected( $probes ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function answer_structure( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $eligible = 0; $questions = 0; $concise = 0; foreach ( $html as $row ) { $answer = $row['signals']['answer_structure'] ?? array(); $eligible += (int) ( $answer['eligible_sections'] ?? 0 ); $questions += (int) ( $answer['question_answer_pairs'] ?? 0 ); $concise += (int) ( $answer['concise_answer_pairs'] ?? 0 ); } $status = array() === $html ? 'not_tested' : ( $eligible > 0 && $questions > 0 ? 'pass' : 'info' ); return $this->crawl_finding( 'aeo.answer_structure', $status, $html, count( $html ), count( $this->page_rows( $snapshot ) ), $timestamp, array( 'structure_inventory_not_answer_quality', 'citation_or_selection_not_tested' ), array( 'eligible:' . $eligible, 'questions:' . $questions, 'concise:' . $concise ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function entity_clarity( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $types = array(); $entities = array(); foreach ( $html as $row ) { $data = $row['signals']['structured_data'] ?? array(); $types = array_merge( $types, is_array( $data['types'] ?? null ) ? $data['types'] : array() ); $entities = array_merge( $entities, is_array( $data['entity_references'] ?? null ) ? $data['entity_references'] : array() ); } $types = array_values( array_unique( array_filter( $types, 'is_string' ) ) ); $entities = array_values( array_unique( array_filter( $entities, 'is_string' ) ) ); $status = array() === $html ? 'not_tested' : ( array() !== $types && array() !== $entities ? 'pass' : 'info' ); return $this->findings->build( 'geo.entity_clarity', $status, array( 'types' => $types, 'parse_results' => array( 'pages' => count( $html ) ), 'entity_ids' => array_slice( $entities, 0, self::REFERENCE_LIMIT ), 'limitations' => array( 'entity_identity_not_externally_resolved', 'citation_not_tested' ), ), count( $html ), count( $this->page_rows( $snapshot ) ), $this->coverage( count( $html ), count( $this->page_rows( $snapshot ) ) ), $timestamp ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function provenance_freshness( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $dated = 0; $authors = 0; $sources = 0; foreach ( $html as $row ) { $data = $row['signals']['provenance'] ?? array(); $dated += (int) ( $data['dated_elements'] ?? 0 ); $authors += (int) ( $data['author_markers'] ?? 0 ); $sources += (int) ( $data['external_reference_links'] ?? 0 ); } $status = array() === $html ? 'not_tested' : ( $dated + $authors + $sources > 0 ? 'pass' : 'info' ); return $this->crawl_finding( 'geo.provenance_freshness', $status, $html, count( $html ), count( $this->page_rows( $snapshot ) ), $timestamp, array( 'presence_not_accuracy', 'date_recency_semantics_not_inferred' ), array( 'dated:' . $dated, 'authors:' . $authors, 'sources:' . $sources ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function publisher_controls( array $snapshot, string $timestamp ): array { $html = $this->html_rows( $this->page_rows( $snapshot ) ); $invalid = 0; $controls = 0; $invalid_rows = array(); foreach ( $html as $row ) { $data = $row['signals']['publisher_controls'] ?? array(); $invalid += (int) ( $data['invalid_data_nosnippet_elements'] ?? 0 ); if ( (int) ( $data['invalid_data_nosnippet_elements'] ?? 0 ) > 0 ) { $invalid_rows[] = $row; } $controls += (int) ( $data['data_nosnippet'] ?? 0 ); $directives = $row['signals']['robots']['directives'] ?? array(); $controls += is_array( $directives ) ? count( $directives ) : 0; } $status = array() === $html ? 'not_tested' : ( $invalid > 0 ? 'warning' : ( $controls > 0 ? 'info' : 'pass' ) ); return $this->crawl_finding( 'geo.publisher_controls', $status, array() === $invalid_rows ? $html : $invalid_rows, count( $html ), count( $this->page_rows( $snapshot ) ), $timestamp, array( 'control_presence_not_provider_behavior', 'provider_specific_interpretation_not_tested' ), array( 'controls:' . $controls, 'invalid:' . $invalid ), array( 'issue_groups' => array() === $invalid_rows ? array() : array( $this->issue_group( 'publisher_control_invalid', $invalid_rows ) ) ) ); } /** * @param list> $snapshot Masked snapshot. * @return array */ private function emerging_files( array $snapshot, string $timestamp ): array { $rows = $this->resource_rows( $snapshot, 'emerging_file' ); $statuses = array_values( array_filter( array_map( static fn ( array $row ): int => (int) ( $row['http_status'] ?? 0 ), $rows ) ) ); $present = array_values( array_filter( $rows, static fn ( array $row ): bool => (int) ( $row['http_status'] ?? 0 ) >= 200 && (int) ( $row['http_status'] ?? 0 ) < 300 ) ); $absent = array_values( array_filter( $rows, static fn ( array $row ): bool => in_array( (int) ( $row['http_status'] ?? 0 ), array( 404, 410 ), true ) ) ); if ( array() === $statuses ) { $status = 'not_tested'; } elseif ( array() !== $present ) { $status = 'info'; } elseif ( array() !== $absent ) { $status = 'pass'; } else { $status = 'info'; } $lines = 0; $h1 = 0; foreach ( $present as $row ) { $lines += (int) ( $row['signals']['line_count'] ?? 0 ); $h1 += (int) ( $row['signals']['h1_count'] ?? 0 ); } return $this->findings->build( 'geo.emerging_files', $status, array( 'objects' => array( 'probe_statuses' => $this->status_counts( $rows ), 'present' => count( $present ), 'absent' => count( $absent ), 'line_count' => $lines, 'h1_count' => $h1, ), 'observed_count' => array() === $statuses ? 0 : 1, 'total_count' => 1, 'truncated' => false, 'limitations' => array( 'experimental_convention', 'not_a_search_requirement', 'provider_usage_not_proven', 'raw_content_not_retained' ), ), array() === $statuses ? 0 : 1, 1, array() === $statuses ? 'none' : 'complete', $timestamp ); } /** * @param list> $snapshot Snapshot rows. * @return list> */ private function resource_rows( array $snapshot, string $resource_class ): array { return array_values( array_filter( $snapshot, static fn ( array $row ): bool => ( $row['resource_class'] ?? '' ) === $resource_class ) ); } /** * @param list> $rows Affected or observed page rows. * @param list $limitations Machine limitation codes. * @param list $extra Safe aggregate evidence. * @param array $evidence_extra Named safe aggregate evidence. * @return array */ private function crawl_finding( string $check_id, string $status, array $rows, int $observed, int $total, string $timestamp, array $limitations, array $extra = array(), array $evidence_extra = array() ): array { $references = $this->references( $rows ); $pages = array_merge( $references, $extra ); $has_issue_groups = is_array( $evidence_extra['issue_groups'] ?? null ) && array() !== $evidence_extra['issue_groups']; return $this->findings->build( $check_id, $status, array_merge( array( 'pages' => array_slice( $pages, 0, self::REFERENCE_LIMIT ), 'observed_count' => $observed, 'discovered_count' => $total, 'truncated' => count( $pages ) > self::REFERENCE_LIMIT, 'crawl_policy' => 'same_origin_queryless_shared_snapshot', 'limitations' => $limitations, ), $evidence_extra ), $observed, $total, $this->coverage( $observed, $total ), $timestamp, $has_issue_groups || in_array( $status, array( 'warning', 'fail' ), true ) ? $this->affected( $rows ) : array() ); } /** * @param list> $snapshot Snapshot rows. * @return list> */ private function page_rows( array $snapshot ): array { return array_values( array_filter( $snapshot, static fn ( array $row ): bool => 'page' === ( $row['resource_class'] ?? '' ) ) ); } /** * @param list> $pages Page rows. * @return list> */ private function html_rows( array $pages ): array { return array_values( array_filter( $pages, static fn ( array $row ): bool => 'observed' === ( $row['state'] ?? '' ) && 'html' === ( $row['content_class'] ?? '' ) && (int) ( $row['http_status'] ?? 0 ) >= 200 && (int) ( $row['http_status'] ?? 0 ) < 300 && 'observed' === ( $row['signals']['state'] ?? '' ) && is_string( $row['signals']['document_reference'] ?? null ) && 1 === preg_match( '/^[a-f0-9]{64}$/', $row['signals']['document_reference'] ) ) ); } /** * @param list> $rows Snapshot rows. * @return list */ private function references( array $rows ): array { $references = array(); foreach ( $rows as $row ) { $reference = $row['url_hash'] ?? null; if ( is_string( $reference ) && 1 === preg_match( '/^[a-f0-9]{64}$/', $reference ) ) { $references[] = $reference; } } return array_slice( array_values( array_unique( $references ) ), 0, self::REFERENCE_LIMIT ); } /** * @param list> $rows Snapshot rows. * @return list */ private function affected( array $rows ): array { $objects = array(); foreach ( $rows as $row ) { $path = $row['display_path'] ?? null; $reference = $row['url_hash'] ?? null; if ( is_string( $path ) && '' !== $path && '/' === $path[0] && strlen( $path ) <= 1536 && false === strpos( $path, '?' ) && false === strpos( $path, '#' ) ) { $objects[] = array( 'type' => 'page_path', 'reference' => $path, ); } elseif ( is_string( $reference ) && 1 === preg_match( '/^[a-f0-9]{64}$/', $reference ) ) { $objects[] = array( 'type' => 'page', 'reference' => $reference, ); } } return array_slice( $this->unique_objects( $objects ), 0, self::REFERENCE_LIMIT ); } /** * @param list $references Safe keyed references. * @param list> $rows Candidate rows for safe paths. * @return list */ private function affected_by_references( array $references, array $rows = array() ): array { $matched = $this->rows_by_references( $rows, $references ); $objects = $this->affected( $matched ); $covered = array_fill_keys( array_map( static fn ( array $row ): string => (string) ( $row['url_hash'] ?? '' ), $matched ), true ); foreach ( array_slice( array_values( array_unique( $references ) ), 0, self::REFERENCE_LIMIT ) as $reference ) { if ( ! isset( $covered[ $reference ] ) && 1 === preg_match( '/^[a-f0-9]{64}$/', $reference ) ) { $objects[] = array( 'type' => 'page', 'reference' => $reference, ); } } return array_slice( $this->unique_objects( $objects ), 0, self::REFERENCE_LIMIT ); } /** * @param array>> $groups Rows grouped by an issue code. * @return list> */ private function issue_groups( array $groups ): array { $out = array(); foreach ( $groups as $code => $rows ) { if ( array() !== $rows ) { $out[] = $this->issue_group( $code, $rows ); } } return $out; } /** * @param list> $rows Affected rows. * @return array */ private function issue_group( string $code, array $rows, int $cluster = 0 ): array { if ( 1 !== preg_match( '/^[a-z][a-z0-9_]{1,63}$/', $code ) || $cluster < 0 ) { throw new InvalidArgumentException( 'invalid_snapshot_issue_group' ); } $safe_objects = array_values( array_filter( $this->affected( $rows ), static fn ( array $item ): bool => 'page_path' === ( $item['type'] ?? null ) ) ); $objects = array_slice( $safe_objects, 0, self::ISSUE_LOCATION_LIMIT ); $private_count = max( 0, count( $rows ) - count( $safe_objects ) ); $limited_count = max( 0, count( $safe_objects ) - count( $objects ) ); return array( 'code' => $code, 'cluster' => $cluster, 'count' => count( $rows ), 'objects' => $objects, 'hidden_count' => $private_count + $limited_count, 'private_count' => $private_count, 'limited_count' => $limited_count, ); } /** * @param list> $rows Snapshot rows. * @param list $references HMAC references. * @return list> */ private function rows_by_references( array $rows, array $references ): array { $wanted = array_fill_keys( $references, true ); return array_values( array_filter( $rows, static fn ( array $row ): bool => isset( $wanted[ (string) ( $row['url_hash'] ?? '' ) ] ) ) ); } /** * @param list $objects Object references. * @return list */ private function unique_objects( array $objects ): array { $unique = array(); foreach ( $objects as $object ) { $unique[ $object['type'] . "\0" . $object['reference'] ] = $object; } return array_values( $unique ); } private function coverage( int $observed, int $total ): string { if ( 0 === $observed ) { return 'none'; } return $observed === $total ? 'complete' : 'partial'; } /** * @param list> $rows Snapshot rows. * @return array */ private function status_counts( array $rows ): array { $counts = array(); foreach ( $rows as $row ) { $status = (int) ( $row['http_status'] ?? 0 ); $key = 0 === $status ? 'unknown' : (string) $status; $counts[ $key ] = ( $counts[ $key ] ?? 0 ) + 1; } return $counts; } }