feat: add types to avoid useless runtime checks

[simPod]

Replace runtime InvalidArgumentException checks with stricter PHPDoc types (non-negative-int, int<0, 1000000>, int<2, 36>), letting PHPStan catch misuse at analysis time instead of at runtime.

The project already uses advanced PHPStan types extensively (level 10, numeric-string, int<1, max>, @phpstan-sealed, purity annotations), so these additions are consistent with the existing type-safety approach. Lib consumers are already expected to use correct types.

Such runtime @throws that can be replaced by types unnecessarily pollute my codebase.
If I know based on types/literals that they're never thrown, I don't have to pretend I catch those.

• BigDecimal
  • dividedBy($scale) → non-negative-int|null
  • sqrt($scale) → non-negative-int
  • power($exponent) → int<0, 1000000>
• BigInteger
  • fromBase($base) → int<2, 36>
  • toBase($base) → int<2, 36>
  • randomBits($numBits) → non-negative-int
  • power($exponent) → int<0, 1000000>
  • isBitSet($n) / testBit($n) → int<0, 1000000>
  • getBitLength() → non-negative-int
  • shiftedRight($distance) → int<-1000000, 1000000>
  • shiftedLeft($distance) → int<-1000000, 1000000>
• BigNumber: toScale($scale) → non-negative-int
• BigRational: power($exponent) → int<0, 1000000>
• Removed corresponding runtime validation checks and @throws InvalidArgumentException lines

[BenMorel]

Hi, replacing runtime checks with type annotations is perfectly OK for internal calls, but unfortunately you can't expect all library consumers to use a static analysis tool.

This library must ensure that you cannot trigger undefined behaviour, whether you're using static analysis or not.

I'll pass on this one, sorry.

[simPod]

mkay

what if we at least keep phpdoc type changes while preserving runtime checks?

[BenMorel]

Yes we can do both, but then we'll need to mute phpstan who will complain that the value is already checked.

I'm not against this change, if you want to draft a PR, please target the v0.15 branch!