Refactor Phase 1: typed enums, readonly Token, full test coverage

[niden]

Summary

This PR completes Phase 1 of the PHQL library refactor — the scanner → AST pipeline. Phase 2 (AST → SQL generation) is deferred.

What changed

New ScannerStatus enum (src/Scanner/ScannerStatus.php)

• Replaces the three magic integer return codes (-1, -2, -3, 0) from scanForToken()
• Cases: EOF = -1, ERR = -2, IMPOSSIBLE = -3, OK = 0

Opcode class → int-backed enum (src/Scanner/Opcode.php)

• Replaces the flat constants class with a proper enum Opcode: int
• Drops the PHQL_T_ prefix throughout (class name provides context)
• Adds a label(): string method returning the operator symbol (+, -, <=, etc.) or the enum name for keywords

Token → final readonly value object (src/Scanner/Token.php)

• Replaces mutable public properties and setters with a constructor-promoted readonly value object
• Constructed as new Token(?Opcode $opcode, ?string $value, int $length)

State cleanup (src/Scanner/State.php)

• Removed unused $end property and setEnd() method
• $activeToken typed as ?Opcode (was mixed with 0 as sentinel)

Status rename (src/Parser/Status.php)

• $ret → $ast, getRet() → getAst(), setRet() → setAst()
• Corresponding call in resources/files/parser.php updated

Scanner updated (src/Scanner/Scanner.php)

• scanForToken() returns ScannerStatus instead of int
• All Opcode::PHQL_T_* references replaced with Opcode::*
• Token construction uses the new readonly value object
• Removed PHQL_SCANNER_RETCODE_* class constants

Parser refactored (src/Parser.php)

• Constructor parameter removed; replaced with fluent setEnableLiterals(bool): static
• switch on opcodes replaced with match on Opcode enum cases
• All exceptions are now Phalcon\Phql\Exception (was RuntimeException)
• Variable names improved ($ret → $ast, $failed → $parseFailed, etc.)

Deleted

• src/Enum.php — superseded by Opcode enum
• src/Tokens.php — unused

Test coverage

• New unit tests for every refactored class: ScannerStatusTest, OpcodeTest, TokenTest, StateTest, StatusTest, ScannerTest, ParserTest
• 208 integration tests ported from cphalcon covering SELECT, INSERT, UPDATE, DELETE statements with all clause combinations
• 267 tests total, 365 assertions, all passing

CI

• PHPStan re-enabled in workflow
• Coverage job now requires tests to pass before running
• Coverage job bumped to PHP 8.5
• phpunit.xml excludes generated resources/files/parser.php from coverage

Test plan

• All 267 tests pass on PHP 8.1–8.5
• PHPStan reports no errors
• PHPCS reports no violations
• Codecov coverage report uploads successfully

[codecov]

Codecov Report

❌ Patch coverage is 97.34151% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.49%. Comparing base (cc93b8f) to head (89924e1).
⚠️ Report is 23 commits behind head on master.

Files with missing lines	Patch %	Lines
src/Scanner/Scanner.php	95.27%	13 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             master       #7       +/-   ##
=============================================
+ Coverage     32.86%   90.49%   +57.63%     
+ Complexity     5598     5042      -556     
=============================================
  Files             7        6        -1     
  Lines          8670     6952     -1718     
=============================================
+ Hits           2849     6291     +3442     
+ Misses         5821      661     -5160     

☔ View full report in Codecov by Sentry.
📢 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.