<?php
/**
 * Contract for scan checks (S-SCAN check registry).
 *
 * @package ForensixDigital
 */

declare(strict_types=1);

namespace ForensixDigital\Services\Scan;

defined( 'ABSPATH' ) || exit;

/**
 * A check looks at one parsed page. It first names the URLs it needs checked over HTTP; the
 * engine checks each URL once per scan and then hands the results to inspect(). Checks never
 * make requests themselves and never change anything.
 */
interface Check {

	/**
	 * Check id, e.g. "scan.broken_link".
	 */
	public function id(): string;

	/**
	 * URLs this check needs results for on this page.
	 *
	 * @param ParsedPage $page Parsed page.
	 * @return string[]
	 */
	public function targets( ParsedPage $page ): array;

	/**
	 * Problems on this page. Each hit has the observation and a short context for this page,
	 * such as the link text. The engine adds the source label.
	 *
	 * @param ParsedPage                  $page    Parsed page.
	 * @param array<string, TargetResult> $results Results for the URLs from targets(), by URL.
	 * @return array<int, array{observation: \ForensixDigital\Services\Findings\Observation, context: string}>
	 */
	public function inspect( ParsedPage $page, array $results ): array;
}