DevEx: phpc lint reports unsupported Stmt/Expr before LogicException

[PurHur]

Problem

When the compiler hits an unsupported construct, lib/Compiler.php throws opaque errors at compile time:

LogicException: Unknown Stmt Type: Stmt\While
LogicException: Unsupported expression: ...

Developers discover gaps only at runtime of phpc run / phpc build, not with file/line context. #192, #53, #99, #114, and #136 are common hits for web apps.

Goal

phpc lint <file> (or bin/vm.php -l) prints a structured, line-accurate list of unsupported syntax in a project entry file and its includes (best-effort).

Scope

• Wrap Compiler::compileStmt / compileExpr catches to attach source line from php-cfg / nikic parser
• Exit non-zero when any unsupported node is found
• Optional --json output for tooling
• Document known unsupported set and link to tracking issues (loops Language: while, do-while, and for loops (CFG → VM → JIT) #192, foreach Language: Implement foreach (CFG → VM → JIT) #53, ?? Language: Null coalescing operator (??) in compiler pipeline #99, etc.)
• Wire into ExamplesCompileTest as optional strict gate

Acceptance criteria

./phpc lint examples/003-MiniWebApp/public/index.php
# reports: line 42: unsupported Stmt\While (see #192)

Exit code 1 when issues exist; 0 when compiles.

Verification

Local only:

./script/ci-local.sh --filter ExamplesCompileTest
./phpc lint -r 'for ($i=0;$i<3;$i++) echo $i;'

Non-goals

• Full PHPStan-level analysis
• Auto-fix or polyfill generation

Related

• Docs: Rewrite README feature list to match current compiler (2026) #48 README capability list
• DevEx: Builtin capability matrix (VM / JIT / AOT per function) #176 capability matrix
• Testing: Example compile gate (VM run + AOT -l for all examples/*.php) #203 example compile gate (closed)

[PurHur]

Merged in #241: phpc lint reports line-accurate unsupported syntax with optional --json and tracking-issue links.