conditional throw

[SignpostMarv]

It's been a while since I delved into the guts of psalm, so I'm wondering if this is one of the traditional "Marv's having ideas that are too weird again" issues, or if it's actually a good idea;

off-label docblock theory:

• combine @throws with existing conditional return syntax with never type to indicate that a method will never throw given a condition
• combine @throws with existing conditional return syntax to indicate which exception will be thrown for a given type
• no [MissingThrowsDocblock](https://psalm.dev/169) thrown if conditional @throws says it is impossible to throw

optional:

• no [UncaughtThrowInGlobalScope](https://psalm.dev/docs/running_psalm/issues/UncaughtThrowInGlobalScope/) in some circumstances- i.e. if @throwsconditionally resolves toclass A extends Exception{}|class B extends Exception{}, and try{} catch(A $e) {}is used in a situation where the conditional throw indicates it would _never_throw B`

Happy to file this as an issue after working through any kinks in the idea here first, also happy to work on it myself (re: past contributions) if I can be given the right pointers as to where to go digging around 😅

/**
 * @template T of positive-int|float|numeric-string
 */
final readonly class Foo
{
    /**
     * @var T
     */
    public int|float|string $value;
    
    /**
     * @param T $value
     * @throws (T is (float|numeric-string) ? RangeException : never) if $value is string and is negative
     */
    public function __construct(
        /** @var T */
        int|float|string $value,
    ) {
        if ($value < 0) {
            throw new RangeException('Only positive numbers supported!');
        }
        
        $this->value = $value;
    }
    
    /**
     * @return non-empty-list<Foo>
     */
    public static function bar(): array
    {
        return [
            new Foo(1), // should not be flagged because positive-int will never be negative
            new Foo(2.0), // should be flagged because there's no positive-float due to https://github.com/vimeo/psalm/issues/5533
            new Foo('1'), // no positive-int-string support either https://github.com/vimeo/psalm/issues/5419
            new Foo('-1'), // should be flagged because it's a numeric string but could be negative
        ];
    }
}

https://psalm.dev/r/7e8f3b86fb

[SignpostMarv]

p.s. yes I realise the @throws description is wrong 😅