<?php

declare(strict_types=1);

namespace App\Exceptions;

use RuntimeException;

/**
 * Raised when OrganisationScope's FK-chain resolver walks past its max
 * hop limit (5 hops — raised from 3 in WS-5c) without reaching a
 * column-based strategy, or when a chain's intermediate model returns
 * an invalid tenantScopeStrategy() shape. Indicates a misconfigured
 * model — fail loud rather than silently leak queries across tenants.
 */
final class TenantScopeResolutionException extends RuntimeException
{
    public static function tooDeep(string $modelClass, int $hops): self
    {
        return new self(sprintf(
            'OrganisationScope FK-chain exceeded %d hops resolving %s — flatten the chain or denormalise organisation_id.',
            $hops,
            $modelClass
        ));
    }

    public static function invalidStrategy(string $modelClass): self
    {
        return new self(sprintf(
            'Model %s::tenantScopeStrategy() must return either ["column" => "..."] or ["via" => FQCN, "fk" => "..."].',
            $modelClass
        ));
    }

    public static function unscopedParent(string $modelClass, string $parentClass): self
    {
        return new self(sprintf(
            'Model %s chains via %s, but the parent exposes neither tenantScopeStrategy() nor $organisationScopeColumn — cannot resolve tenant.',
            $modelClass,
            $parentClass
        ));
    }
}