<?php
/**
 * Audit check for the page's structured data as a WHOLE (as opposed to
 * ABDS_SEO_Site_Scanner's per-type "is this rich result complete" rules):
 * is there any, do its references hold together, do two sources describe the
 * same thing, and is another SEO plugin in charge of it.
 *
 * Findings, all reported from the audit's own scan of the rendered page, never
 * from a front-end request:
 *  - schema_missing        no JSON-LD node on the page at all.
 *  - schema_graph_broken   a reference to an @id the graph does not define, or an
 *
 *                          @id defined twice.
 *  - schema_conflict       two nodes of a type that should be unique (two
 *                          organizations, two WebSite nodes, two Articles...),
 *                          typically from a theme or a second plugin.
 *  - schema_type_invalid   the schema type stored for this content type is not one
 *                          the graph prints, so Article is used instead.
 *  - schema_other_plugin   another SEO plugin is active; ABDS SEO then prints no
 *                          structured data of its own (compatibility mode) and the
 *                          graph on the page is that plugin's. Information only:
 *                          nothing is switched off and nobody else's output is
 *                          touched.
 *
 * @package ABDS_SEO
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Whole-page structured-data findings.
 */
class ABDS_SEO_Audit_Check_Schema implements ABDS_SEO_Audit_Check {

	const CATEGORY = 'technical';

	/**
	 * Competitor detector (injectable for tests).
	 *
	 * @var ABDS_SEO_Compat_Detector
	 */
	protected ABDS_SEO_Compat_Detector $compat;

	/**
	 * Constructor.
	 *
	 * @param ABDS_SEO_Compat_Detector|null $compat Optional detector override.
	 */
	public function __construct( ?ABDS_SEO_Compat_Detector $compat = null ) {
		$this->compat = $compat ?? new ABDS_SEO_Compat_Detector();
	}

	/**
	 * Runs the check for one page.
	 *
	 * @param WP_Post $post Post being audited.
	 * @param string  $html Rendered page HTML ('' when it could not be fetched).
	 * @return array<int,array{issue_key:string,category:string,severity:string,message:string,details:array}>
	 */
	public function run( WP_Post $post, string $html ): array {
		$issues = array();

		$stored   = ABDS_SEO_Policy_Engine::stored_schema_type_for_post_type( $post->post_type );
		$resolved = '' !== $stored ? ABDS_SEO_Schema_Validator::resolve_page_type( $stored, $post->post_type ) : array( 'valid' => true );
		if ( ! $resolved['valid'] ) {
			$issues[] = $this->issue(
				'schema_type_invalid',
				'medium',
				sprintf(
					/* translators: 1: the schema type saved for this content type, 2: the type printed instead. */
					__( 'The schema type "%1$s" saved for this content type cannot be printed; %2$s is used instead.', 'abds-seo' ),
					$stored,
					$resolved['type']
				),
				array( 'stored_type' => $stored )
			);
		}

		$plugins = array_map( array( ABDS_SEO_Compat_Detector::class, 'label' ), $this->compat->active_competitors() );
		if ( array() !== $plugins ) {
			$issues[] = $this->issue(
				'schema_other_plugin',
				'notice',
				sprintf(
					/* translators: %s: comma-separated names of the other active SEO plugins. */
					__( 'Another SEO plugin is active (%s), so any structured data on this page comes from it, not from ABDS SEO.', 'abds-seo' ),
					implode( ', ', $plugins )
				),
				array( 'plugins' => $plugins )
			);
		}

		if ( '' === $html ) {
			return $issues;
		}

		$analysis = ABDS_SEO_Schema_Validator::analyze_html( $html );

		if ( 0 === $analysis['node_count'] ) {
			$issues[] = $this->issue(
				'schema_missing',
				'low',
				__( 'The page has no structured data.', 'abds-seo' )
			);

			return $issues;
		}

		if ( array() !== $analysis['dangling'] || array() !== $analysis['duplicate_ids'] ) {
			$issues[] = $this->issue(
				'schema_graph_broken',
				'medium',
				__( 'The page\'s structured data refers to items that are not described, or describes the same item twice.', 'abds-seo' ),
				array(
					'dangling'      => $analysis['dangling'],
					'duplicate_ids' => $analysis['duplicate_ids'],
				)
			);
		}

		if ( array() !== $analysis['duplicate_types'] ) {
			$issues[] = $this->issue(
				'schema_conflict',
				'medium',
				sprintf(
					/* translators: %s: comma-separated names of the duplicated structured-data types. */
					__( 'The page\'s structured data describes more than one of: %s. Search engines will pick one of them.', 'abds-seo' ),
					implode( ', ', array_keys( $analysis['duplicate_types'] ) )
				),
				array( 'types' => $analysis['duplicate_types'] )
			);
		}

		return $issues;
	}

	/**
	 * One normalised audit issue.
	 *
	 * @param string $key      issue_key.
	 * @param string $severity critical|high|medium|low|notice.
	 * @param string $message  Human message.
	 * @param array  $details  Structured details for the report.
	 * @return array
	 */
	protected function issue( string $key, string $severity, string $message, array $details = array() ): array {
		return array(
			'issue_key' => $key,
			'category'  => self::CATEGORY,
			'severity'  => $severity,
			'message'   => $message,
			'details'   => $details,
		);
	}
}