<?php
/**
 * R3: the contract every audit check adapts an existing analyzer to. One
 * check runs against one already-fetched page and returns zero or more
 * normalized issues — never touches the database itself (ABDS_SEO_Audit_Engine
 * is the only writer, so every check's output lands in wp_abds_seo_audit_issues
 * the same shape regardless of which underlying analyzer produced it).
 *
 * @package ABDS_SEO
 */

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

/**
 * One audit check, adapting an existing analyzer's own output shape to the
 * normalized audit-issue shape.
 */
interface ABDS_SEO_Audit_Check {

	/**
	 * Runs this check against one post.
	 *
	 * @param WP_Post $post Post being audited.
	 * @param string  $html The post's rendered HTML — fetched once per URL by
	 *                      ABDS_SEO_Audit_Engine and shared across every
	 *                      registered check, not fetched per-check.
	 * @return array<int, array{issue_key:string, category:string, severity:string, message:string, details:array}>
	 *               `severity` is always one of the 5 wp_abds_seo_audit_issues
	 *               levels (critical/high/medium/low/notice) — never the
	 *               older 3-level critical/warning/info vocabulary some
	 *               wrapped analyzers still use internally; each adapter's
	 *               own docblock documents its specific mapping table.
	 */
	public function run( WP_Post $post, string $html ): array;
}