<?php

declare(strict_types=1);

namespace Plugin\tnt_mcp\src\Mcp\Action;

use RuntimeException;

/**
 * A `compatibleShopVersions:` string {@see ShopVersionRange} refuses to interpret — or a shop
 * version it cannot read.
 *
 * Thrown rather than degraded on purpose. The gate this feeds decides whether catalog entries are
 * offered to an LLM that will then POST to a live backend controller; a range that was *guessed at*
 * is strictly worse than no feature at all, because a mis-parsed `<5.9.0` reads as "supported"
 * against 5.11 and the caller finds out by writing a half-bound row. Fail here, loudly, at parse
 * time.
 */
final class UnsupportedVersionRangeException extends RuntimeException
{
    public static function unsupportedOperator(string $range, string $clause): self
    {
        return new self(\sprintf(
            'compatibleShopVersions "%s": clause "%s" uses an operator this plugin does not '
            . 'implement. Supported grammar: one or more whitespace-separated clauses, each ">=" or '
            . '"<" followed by a version (e.g. ">=5.5.0 <5.9.0"); all clauses must hold. '
            . 'Caret/tilde/wildcard/hyphen ranges, "||", "=", ">" and "<=" are NOT supported — add '
            . 'them to ShopVersionRange deliberately rather than letting one be mis-read.',
            $range,
            $clause
        ));
    }

    public static function emptyRange(string $range): self
    {
        return new self(\sprintf(
            'compatibleShopVersions "%s" is empty: a range with no clause would admit every shop '
            . 'version, which is a decision the catalog file has to state, not omit.',
            $range
        ));
    }

    public static function malformedVersion(string $context, string $version): self
    {
        return new self(\sprintf(
            '%s: "%s" is not a version this plugin can compare. Expected 1 to 3 dot-separated '
            . 'numbers with an optional leading "v" and an optional -prerelease/+build suffix '
            . '(e.g. "5.8", "5.8.0", "5.8.0-rc.2").',
            $context,
            $version
        ));
    }
}
