Restore instanceof WP_Parser for the native parser (#393)

Addresses Jan's note on #381: in native mode, `new WP_MySQL_Parser(...)
instanceof WP_Parser` returns false because the native-mode class
extends the Rust-registered `WP_MySQL_Native_Parser`, which has no
`WP_Parser` in its chain. Existing downstream code doing `if ($parser
instanceof WP_Parser)` silently skipped the parser whenever the
extension was loaded.

This restores the contract by always extending the pure-PHP `WP_Parser`
and pulling the native-mode behaviour in via a trait:

```php
class WP_MySQL_Parser extends WP_Parser {
    use WP_MySQL_Native_Parser_Impl;
}
```

`WP_MySQL_Native_Parser_Impl` owns the composed `WP_MySQL_Native_Parser`
instance and the four-method delegation surface (`parse`, `next_query`,
`get_query_ast`, `reset_tokens`). `WP_Parser`'s protected state
(`$grammar`, `$tokens`, `$position`) is initialised by
`parent::__construct` and stays inert — the trait's overrides never read
it.

Adding a public method later means adding it to the trait — the class
file itself is two lines and doesn't need touching.

## Why a trait, not a private property?

A bare property would also work, but the trait keeps the class file
expressing only the routing decision (`extends WP_Parser` + `use
Rust_Implementation;`). The implementation lives in one place, symmetric
to where a future PHP-mode trait could live if we ever want to mirror
the structure. Behaviour-wise the two are equivalent.

## Performance

The trait adds **one extra method-call frame per public-API call**. The
public API is `parse()`, `next_query()`, `get_query_ast()`,
`reset_tokens()` — called once per query. The actual parsing work
happens inside the native call, so the delegation overhead is a small
constant per query, not a multiplier on the parsing work.

The `Parser Delegation Perf` workflow runs
`tests/tools/run-parser-benchmark.php` (parses the full MySQL
server-suite corpus, ~70k queries) three times on this PR and three
times on the PR base, on the same runner, with the extension loaded both
times. The comparison goes into the job summary on every push.

## Test plan

- [x] PHP-only PHPUnit suite passes.
- [ ] PHPUnit suite passes with the native extension loaded; the new
`WP_MySQL_Parser_Instanceof_Tests` confirm `instanceof WP_Parser` and
`instanceof WP_MySQL_Parser` both hold.
- [ ] `Parser Delegation Perf` workflow shows the delegation cost is
within noise.

Author: adamziel

.github/workflows/parser-delegation-perf.yml

@@ -0,0 +1,146 @@
+name: Parser Delegation Perf
+
+# Measures the wall-time cost of routing the public parser API through a
+# composed `WP_MySQL_Native_Parser` instance (this PR) instead of letting
+# `WP_MySQL_Parser` directly extend the Rust class (PR base). The parse
+# benchmark walks the full MySQL server-suite corpus on both branches —
+# the delta is the per-call delegation cost.
+
+on:
+  push:
+    paths:
+      - '.github/workflows/parser-delegation-perf.yml'
+      - 'packages/mysql-on-sqlite/src/mysql/native/**'
+      - 'packages/mysql-on-sqlite/tests/tools/run-parser-benchmark.php'
+      - 'packages/php-ext-wp-mysql-parser/**'
+  pull_request:
+    paths:
+      - '.github/workflows/parser-delegation-perf.yml'
+      - 'packages/mysql-on-sqlite/src/mysql/native/**'
+      - 'packages/mysql-on-sqlite/tests/tools/run-parser-benchmark.php'
+      - 'packages/php-ext-wp-mysql-parser/**'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  perf:
+    name: Parser delegation benchmark
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          coverage: none
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install native build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libclang-dev
+          echo "PHP_CONFIG=$(command -v php-config)" >> "$GITHUB_ENV"
+          LIBCLANG_SO="$(find /usr/lib -name 'libclang.so*' | head -n 1)"
+          echo "LIBCLANG_PATH=$(dirname "$LIBCLANG_SO")" >> "$GITHUB_ENV"
+
+      - name: Install Composer dependencies (root)
+        uses: ramsey/composer-install@v3
+        with:
+          ignore-cache: "yes"
+          composer-options: "--optimize-autoloader"
+
+      - name: Install Composer dependencies (mysql-on-sqlite)
+        uses: ramsey/composer-install@v3
+        with:
+          working-directory: packages/mysql-on-sqlite
+          ignore-cache: "yes"
+          composer-options: "--optimize-autoloader"
+
+      - name: Download MySQL test query corpus
+        working-directory: packages/mysql-on-sqlite
+        run: bash tests/tools/mysql-download-tests.sh || true
+
+      - name: Build parser extension (release)
+        run: cargo build --release
+        working-directory: packages/php-ext-wp-mysql-parser
+
+      - name: Locate built extension
+        run: |
+          EXT="$GITHUB_WORKSPACE/packages/php-ext-wp-mysql-parser/target/release/libwp_mysql_parser.so"
+          test -f "$EXT" || { echo "Extension not built at $EXT"; exit 1; }
+          echo "NATIVE_EXT=$EXT" >> "$GITHUB_ENV"
+
+      - name: Benchmark — this PR (trait delegation)
+        working-directory: packages/mysql-on-sqlite
+        run: |
+          for i in 1 2 3; do
+            echo "=== run $i ==="
+            php -d extension="$NATIVE_EXT" tests/tools/run-parser-benchmark.php
+          done | tee "$GITHUB_WORKSPACE/this-pr.txt"
+
+      - name: Check out baseline (PR base, direct extends)
+        run: |
+          git fetch --no-tags --depth=1 origin codex/native-lazy-ast-facade
+          git worktree add ../baseline FETCH_HEAD
+
+      - name: Install Composer dependencies (baseline)
+        uses: ramsey/composer-install@v3
+        with:
+          working-directory: ../baseline/packages/mysql-on-sqlite
+          ignore-cache: "yes"
+          composer-options: "--optimize-autoloader"
+
+      - name: Build baseline parser extension (release)
+        run: cargo build --release
+        working-directory: ../baseline/packages/php-ext-wp-mysql-parser
+
+      - name: Stage corpus into baseline
+        run: |
+          mkdir -p ../baseline/packages/mysql-on-sqlite/tests/mysql/data
+          cp packages/mysql-on-sqlite/tests/mysql/data/*.csv \
+             ../baseline/packages/mysql-on-sqlite/tests/mysql/data/ 2>/dev/null || true
+
+      - name: Benchmark — baseline (direct extends)
+        working-directory: ../baseline/packages/mysql-on-sqlite
+        run: |
+          BASE_EXT="$(realpath ../../packages/php-ext-wp-mysql-parser/target/release/libwp_mysql_parser.so)"
+          for i in 1 2 3; do
+            echo "=== run $i ==="
+            php -d extension="$BASE_EXT" tests/tools/run-parser-benchmark.php
+          done | tee "$GITHUB_WORKSPACE/baseline.txt"
+
+      - name: Summarize
+        if: always()
+        run: |
+          {
+            echo '### Parser delegation perf'
+            echo
+            echo '#### This PR (`use WP_MySQL_Native_Parser_Impl;`)'
+            echo '```'
+            cat "$GITHUB_WORKSPACE/this-pr.txt" 2>/dev/null || echo 'no output'
+            echo '```'
+            echo
+            echo '#### Baseline (`extends WP_MySQL_Native_Parser`)'
+            echo '```'
+            cat "$GITHUB_WORKSPACE/baseline.txt" 2>/dev/null || echo 'no output'
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload raw output
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: parser-delegation-perf-${{ github.run_id }}
+          path: |
+            this-pr.txt
+            baseline.txt
+          if-no-files-found: warn

packages/mysql-on-sqlite/src/load.php

@@ -28,6 +28,7 @@
 if ( class_exists( 'WP_MySQL_Native_Parser', false ) ) {
 	require_once __DIR__ . '/mysql/native/mysql-rust-bridge.php';
 	require_once __DIR__ . '/mysql/native/class-wp-mysql-native-parser-node.php';
+	require_once __DIR__ . '/mysql/native/trait-wp-mysql-native-parser-impl.php';
 	require_once __DIR__ . '/mysql/native/class-wp-mysql-parser.php';
 } else {
 	require_once __DIR__ . '/mysql/class-wp-mysql-parser.php';

packages/mysql-on-sqlite/src/mysql/native/class-wp-mysql-parser.php

@@ -1,3 +1,14 @@
 <?php
 
-class WP_MySQL_Parser extends WP_MySQL_Native_Parser {}
+/**
+ * Native-mode public parser entry point.
+ *
+ * Always extends the pure-PHP `WP_Parser` so `$parser instanceof WP_Parser`
+ * keeps working for callers regardless of whether the Rust extension is
+ * loaded. The actual parsing work is delegated to a composed
+ * `WP_MySQL_Native_Parser` instance via the `WP_MySQL_Native_Parser_Impl`
+ * trait — see that file for the per-method delegation.
+ */
+class WP_MySQL_Parser extends WP_Parser {
+	use WP_MySQL_Native_Parser_Impl;
+}

packages/mysql-on-sqlite/src/mysql/native/trait-wp-mysql-native-parser-impl.php

@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * Native-mode `WP_MySQL_Parser` implementation, delivered as a trait.
+ *
+ * The class that uses this trait (`WP_MySQL_Parser` in native mode)
+ * extends the pure-PHP `WP_Parser` so callers' `instanceof WP_Parser`
+ * checks keep working, while the actual parsing work is delegated to
+ * the Rust-registered `WP_MySQL_Native_Parser` instance held in
+ * `$this->native`. `WP_Parser`'s state (`$grammar`, `$tokens`,
+ * `$position`) stays inert in native mode — the trait's overrides
+ * never read it.
+ *
+ * Adding a public method here is enough to plumb a new public method
+ * through to the native parser; the using class does not need touching.
+ */
+trait WP_MySQL_Native_Parser_Impl {
+	/**
+	 * @var WP_MySQL_Native_Parser
+	 */
+	private $native;
+
+	/**
+	 * @param WP_Parser_Grammar                          $grammar
+	 * @param array<WP_Parser_Token>|WP_MySQL_Native_Token_Stream $tokens
+	 */
+	public function __construct( WP_Parser_Grammar $grammar, $tokens ) {
+		// WP_Parser's `array $tokens` constructor signature can't accept
+		// the native token stream object; its `$this->tokens` /
+		// `$this->position` state is inert in native mode anyway, so we
+		// pass an empty array to satisfy the parent contract and keep
+		// the actual tokens on the native parser.
+		parent::__construct( $grammar, array() );
+		$this->native = new WP_MySQL_Native_Parser( $grammar, $tokens );
+	}
+
+	/**
+	 * @param array<WP_Parser_Token>|WP_MySQL_Native_Token_Stream $tokens
+	 */
+	public function reset_tokens( $tokens ): void {
+		$this->native->reset_tokens( $tokens );
+	}
+
+	public function next_query(): bool {
+		return $this->native->next_query();
+	}
+
+	public function get_query_ast(): ?WP_Parser_Node {
+		return $this->native->get_query_ast();
+	}
+
+	public function parse() {
+		return $this->native->parse();
+	}
+}

packages/mysql-on-sqlite/tests/mysql/native/WP_MySQL_Parser_Instanceof_Tests.php

@@ -0,0 +1,40 @@
+<?php
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * `WP_MySQL_Parser instanceof WP_Parser` must hold in both modes.
+ *
+ * Pre-PR, the native-mode `WP_MySQL_Parser` was `extends WP_MySQL_Native_Parser`
+ * (a Rust-registered class with no `WP_Parser` in its chain), so existing
+ * downstream code doing `if ($parser instanceof WP_Parser)` silently
+ * skipped the parser when the extension was loaded. This test pins the
+ * contract for both modes.
+ */
+class WP_MySQL_Parser_Instanceof_Tests extends TestCase {
+
+	public function test_parser_is_instance_of_wp_parser(): void {
+		$grammar = new WP_Parser_Grammar( include __DIR__ . '/../../../src/mysql/mysql-grammar.php' );
+		$lexer   = new WP_MySQL_Lexer( 'SELECT 1' );
+		$tokens  = $lexer instanceof WP_MySQL_Native_Lexer
+			? $lexer->native_token_stream()
+			: $lexer->remaining_tokens();
+		$parser  = new WP_MySQL_Parser( $grammar, $tokens );
+
+		$this->assertInstanceOf( WP_Parser::class, $parser );
+		$this->assertInstanceOf( WP_MySQL_Parser::class, $parser );
+	}
+
+	public function test_parser_returns_an_ast(): void {
+		$grammar = new WP_Parser_Grammar( include __DIR__ . '/../../../src/mysql/mysql-grammar.php' );
+		$lexer   = new WP_MySQL_Lexer( 'SELECT 1 + 2' );
+		$tokens  = $lexer instanceof WP_MySQL_Native_Lexer
+			? $lexer->native_token_stream()
+			: $lexer->remaining_tokens();
+		$parser  = new WP_MySQL_Parser( $grammar, $tokens );
+
+		$ast = $parser->parse();
+		$this->assertNotNull( $ast );
+		$this->assertInstanceOf( WP_Parser_Node::class, $ast );
+	}
+}