feat(SelectQuery): refine Psalm integer types on query bounds

[roxblnfk]

🔍 What was changed

Refined the Psalm types in SelectQuery so numeric bounds and string constraints are expressed at the type level.

Added integer bounds:

Method	Annotation	Meaning
runChunks()	@param int<1, max> $limit	Chunk size must be positive — a non-positive value never advances the offset and would spin in an endless loop.
getLimit()	@return int<0, max>|null	Limit is >= 0 or null (0 disables limiting).
getOffset()	@return int<0, max>|null	Offset is >= 0 or null.
count()	@return int<0, max>	A row count is never negative.

Simplified existing hints: dropped the redundant psalm- prefix from the non-empty-string column/method hints on count(), avg(), max(), min(), sum() and runAggregate() — plain @param advanced types are now broadly supported (Psalm, PHPStan, PhpStorm).

Note

Annotation-only — runtime behaviour and public signatures are unchanged.

🤔 Why?

Expressing these bounds as Psalm types lets static analysis catch invalid values at the call site instead of failing (or hanging) at runtime, and gives consumers more precise return types. The endless-loop risk on a non-positive chunk size was surfaced by the Copilot review on #255.

Setter params (limit() / offset()) are intentionally left as-is: narrowing them would break the Spiral\Pagination\PaginableInterface contract (MoreSpecificImplementedParamType). The return-type refinements are safe because LessSpecificReturnStatement / MoreSpecificReturnType are already suppressed project-wide in psalm.xml.

📝 Checklist

• How was this tested:

  • Tested manually
  • Unit tests added

  Verified with psalm (no new issues introduced) and php-cs-fixer (clean). No unit tests are added — these are static-analysis annotations with no runtime effect.

📃 Documentation

Not needed — type-level annotations, public API signatures unchanged.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.68%. Comparing base (38c3403) to head (39d0018).

Additional details and impacted files

@@            Coverage Diff            @@
##                2.x     #257   +/-   ##
=========================================
  Coverage     95.68%   95.68%           
  Complexity     2038     2038           
=========================================
  Files           137      137           
  Lines          5775     5775           
=========================================
  Hits           5526     5526           
  Misses          249      249           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.