<?php

declare(strict_types=1);

namespace LIT\MCP\Integrations\Divi\Library;

defined('ABSPATH') || exit;

/**
 * What GlobalUsages looks for (ruling P23 pattern, fail closed): a prepared SQL condition on post_content that
 * keeps every post that may reference the thing (one query, ID/status/type only), and the decision on the
 * content of each candidate. A library entry (LibraryUsageQuery), a preset (PresetUsageQuery, Etappe 4) …
 */
interface UsageQuery
{
    /**
     * MySQL REGEXP for a JSON-escaped letter ("\\u004x" … "\\u007x"): a name or ID written that way is not found by
     * LIKE, so candidate conditions keep such posts (fail closed, ruling P23).
     */
    public const ESCAPED_LETTER_REGEX = '\\\\u00[4-7][0-9a-fA-F]';

    /** A condition for "WHERE (…)", already passed through $db->prepare(). */
    public function candidateCondition(\wpdb $db): string;

    /** Whether $content references the thing; true when unsure (fail closed). */
    public function matches(string $content): bool;
}