Merge pull request #5 from bordoni/feature/phpstan

chore(tooling): add PHPStan level 5 to dev tooling + CI

Author: bordoni

.github/workflows/test.yml

@@ -35,6 +35,48 @@ jobs:
       - name: Run PHPCS
         run: vendor/bin/phpcs
 
+  phpstan:
+    name: PHPStan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          tools: composer
+          coverage: none
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Setup bun
+        uses: oven-sh/setup-bun@v2
+
+      # Composer install MUST run scripts here (unlike the PHPCS job above)
+      # so Strauss generates the prefixed `WorkOS\Vendor\…` classes that
+      # PHPStan needs to resolve types.
+      - name: Install PHP dependencies (with Strauss)
+        run: composer install --no-interaction --prefer-dist
+        env:
+          COMPOSER_NO_AUDIT: 1
+
+      # Build the JS bundles so the `build/*.asset.php` files exist —
+      # PHPStan statically resolves the `include $asset_file` paths in
+      # Admin/Settings.php, UI/Controller.php, etc. and would otherwise
+      # fail with `path.notExists` even though every callsite is guarded
+      # by `file_exists()`.
+      - name: Install JS dependencies + build
+        run: |
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Run PHPStan
+        run: composer phpstan -- --no-progress --error-format=github
+
   tests-php:
     name: PHP Tests (PHP ${{ matrix.php }})
     runs-on: ubuntu-latest

.gitignore

@@ -9,6 +9,10 @@
 *.cache
 *.log
 
+# PHPStan baseline — fix-everything policy; do not commit a baseline
+# file without team discussion (see AGENTS.md > Static Analysis).
+/phpstan-baseline.neon
+
 # Lock files
 package-lock.json
 

AGENTS.md

@@ -180,6 +180,8 @@ Per-environment constants (take priority over generic):
 | `bun.lock` | Locked dependency graph (committed) |
 | `tsconfig.json` | TypeScript config (strict, `jsx: react-jsx`, `noEmit: true`) |
 | `webpack.config.js` | Extends `@wordpress/scripts` default config with authkit + admin-profiles entries |
+| `phpstan.neon.dist` | PHPStan config (level 5, scans `src/` + `integration-workos.php` + `uninstall.php`, `phpVersion: 70400`, Strauss vendor resolved via `vendor/autoload.php` in `scanFiles`) |
+| `phpstan/stubs.php` | Symbol stubs for `WORKOS_*` runtime-defined constants so PHPStan can resolve them statically — never executed |
 
 ## Build System
 
@@ -197,6 +199,7 @@ bun run start         # Development with watch
 bun run lint:ts       # Type-check TypeScript (tsc --noEmit)
 bun run lint:php      # Lint PHP via PHPCS
 bun run lint:php:fix  # Auto-fix PHP lint issues
+composer phpstan      # Static analysis (PHPStan level 5, --memory-limit=1G)
 ```
 
 `@wordpress/scripts` v30 transpiles `.ts` / `.tsx` natively via its default
@@ -297,3 +300,47 @@ Use the global `/slic` skill for comprehensive guidance on test structure, envir
 
 - PHP follows WordPress Coding Standards via PHPCS/WPCS
 - Run `composer lint` / `composer lint:fix` for PHP linting
+
+## Static Analysis (PHPStan)
+
+PHPStan analyses the plugin source at **level 5** and is gated in CI as
+a required check on PRs to `main`. Config: `phpstan.neon.dist`.
+
+### Stack
+
+- `phpstan/phpstan` ^2 — analyzer, in `composer require-dev`
+- `szepeviktor/phpstan-wordpress` — WordPress core stubs + WP-aware
+  inference for `apply_filters`, `wp_remote_request`, hook signatures
+- `php-stubs/wp-cli-stubs` — `WP_CLI`, `WP_CLI_Command`,
+  `WP_CLI\Formatter` for `src/WorkOS/CLI/*`
+- `phpstan/extension-installer` — auto-registers neon files from
+  installed extensions (no manual `includes:` wiring)
+
+### Scope
+
+- Scanned: `src/`, `integration-workos.php`, `uninstall.php`
+- `phpVersion: 70400` so PHP 7.4 syntax mistakes can't slip past on
+  PHP 8.x runners
+- `treatPhpDocTypesAsCertain: false` — narrowing is required when a
+  hook caller may pass something other than the documented type
+- Strauss-prefixed `WorkOS\Vendor\…` resolved via `vendor/autoload.php`
+  in `scanFiles`. The PHPStan CI job therefore must run
+  `composer install` WITH scripts (so Strauss runs and prefixed
+  classes exist on disk) — that's the key difference from the PHPCS
+  CI job, which uses `--no-scripts` + a stub `vendor/prefixed/autoload.php`.
+- WP-CLI stubs (`vendor/php-stubs/wp-cli-stubs/wp-cli-*.php`) and
+  `phpstan/stubs.php` (project-local `WORKOS_*` constants) are loaded
+  via `scanFiles`. Not bootstrap files — just symbol discovery.
+
+### Policy
+
+- **No baseline.** Findings get fixed in the PR that introduces them.
+  `composer phpstan:baseline` exists as a safety hatch for
+  exceptional cases but the resulting `phpstan-baseline.neon` should
+  not be committed without discussion.
+- **Tests are not analyzed yet.** Codeception's wp-browser stubs are
+  partial; revisit once `phpstan/phpstan-phpunit` integration is
+  worth the noise.
+- **Strict-rules extension is intentionally not enabled.** Level 5 is
+  the floor we're committing to first; reconsider strict-rules as a
+  follow-up when this is stable.

README.md

@@ -791,6 +791,38 @@ composer lint:fix     # PHP (auto-fix)
 bun run lint:ts       # TypeScript
 ```
 
+### Static Analysis (PHPStan)
+
+PHPStan runs at **level 5** against `src/`, `integration-workos.php`,
+and `uninstall.php`. The config lives in `phpstan.neon.dist` and is
+enforced by the `PHPStan` GitHub Actions job — PRs to `main` cannot
+merge while it's red.
+
+```bash
+composer phpstan            # Run analysis (--memory-limit=1G)
+composer phpstan:baseline   # Generate phpstan-baseline.neon (fix-everything policy: do not commit)
+```
+
+The stack:
+
+- `phpstan/phpstan` ^2 — analyzer
+- `szepeviktor/phpstan-wordpress` — WordPress core stubs + WP-aware
+  inference (handles `apply_filters`, `wp_remote_request`, hook
+  signatures)
+- `php-stubs/wp-cli-stubs` — `WP_CLI`, `WP_CLI_Command`,
+  `WP_CLI\Formatter`, etc. for the `src/WorkOS/CLI/*` commands
+- `phpstan/extension-installer` — auto-registers extension neon files
+
+`phpstan/stubs.php` declares the `WORKOS_*` constants that
+`Plugin::init()` defines at runtime so PHPStan can resolve them at
+parse time. Strauss-prefixed `WorkOS\Vendor\…` classes are picked up
+automatically via `vendor/autoload.php` in `scanFiles`.
+
+**Policy: no baseline.** Findings must be fixed in the PR that
+introduces them. The `composer phpstan:baseline` script exists as a
+safety hatch, but the resulting file should not be committed without
+discussion.
+
 ### Architecture
 
 The plugin uses a DI container (di52) with a feature-controller pattern:

composer.json

@@ -24,8 +24,12 @@
 		"codeception/module-filesystem": "^3.0",
 		"dealerdirect/phpcodesniffer-composer-installer": "^1.0",
 		"lucatume/wp-browser": "^4.5",
+		"php-stubs/wp-cli-stubs": "^2.11",
 		"phpcompatibility/phpcompatibility-wp": "^2.1",
+		"phpstan/extension-installer": "^1.4",
+		"phpstan/phpstan": "^2.0",
 		"squizlabs/php_codesniffer": "^3.8",
+		"szepeviktor/phpstan-wordpress": "^2.0",
 		"wp-coding-standards/wpcs": "^3.0"
 	},
 	"autoload": {
@@ -36,14 +40,17 @@
 	},
 	"config": {
 		"allow-plugins": {
-			"dealerdirect/phpcodesniffer-composer-installer": true
+			"dealerdirect/phpcodesniffer-composer-installer": true,
+			"phpstan/extension-installer": true
 		},
 		"sort-packages": true
 	},
 	"scripts": {
 		"test:wpunit": "vendor/bin/codecept run wpunit",
 		"lint": "phpcs",
 		"lint:fix": "phpcbf",
+		"phpstan": "phpstan analyse --memory-limit=1G",
+		"phpstan:baseline": "phpstan analyse --memory-limit=1G --generate-baseline",
 		"strauss-install": [
 			"test -f ./bin/strauss.phar || (mkdir -p bin && curl -o bin/strauss.phar -L https://github.com/BrianHenryIE/strauss/releases/download/0.26.5/strauss.phar)"
 		],