0.3.x

.github/workflows/ci-core.yml

@@ -66,6 +66,53 @@ jobs:
       - name: Run PHPStan
         run: make lint/phpstan
 
+  phpstan-pass:
+    # The `xphp check` PHPStan-integration tests (@group phpstan) shell out to a
+    # real phpstan binary, so they're excluded from `make test/unit` and run here.
+    # `composer install` provides vendor/bin/phpstan (a require-dev dependency).
+    name: PHPStan pass (xphp check)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        uses: ramsey/composer-install@v3
+
+      - name: Run the PHPStan-pass tests
+        run: make test/phpstan-pass
+
+  check:
+    # End-to-end self-test of the `xphp check` gate: runs the real bin/xphp
+    # binary against the check fixtures and asserts the 0/1/2 exit contract.
+    # The in-process CheckCommandTest can't observe the shipped binary's
+    # process exit code or its rendered stdout, so this covers that gap.
+    name: xphp check (self-test)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP 8.4
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: dom, json, mbstring, tokenizer
+          coverage: none
+          tools: composer:v2
+
+      - name: Install dependencies
+        uses: ramsey/composer-install@v3
+
+      - name: Run xphp check self-test
+        run: make test/check
+
   infection:
     name: Mutation testing
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -36,6 +36,13 @@ jobs:
         # release fails BEFORE the asset is uploaded.
         run: php dist/xphp.phar list
 
+      - name: Smoke-test `check` on the PHAR
+        # Exercise the released artifact as a real gate: same 0/1/2
+        # exit-contract assertions as CI, but against dist/xphp.phar
+        # instead of bin/xphp. Fails the release before upload if the
+        # packaged binary can't validate sources.
+        run: make test/check XPHP_BIN="php dist/xphp.phar"
+
       - name: Compute SHA256 sum
         # `sha256sum` outputs `<hex>  <filename>`; running it from
         # the dist/ directory keeps the filename relative so users

CONTRIBUTING.md

@@ -3,16 +3,24 @@
 ## Test
 
 ```bash
-make test/unit        # PHPUnit on the default PHP 8.4 runtime
-make test/unit/php85  # only tests tagged `@group php85`; needs a PHP 8.5 runtime
-make test/mutation    # Infection, MSI under a 95 % gate
+make test/unit          # PHPUnit on the default PHP 8.4 runtime
+make test/unit/php85    # only tests tagged `@group php85`; needs a PHP 8.5 runtime
+make test/phpstan-pass  # only tests tagged `@group phpstan` (the `xphp check` PHPStan pass)
+make test/mutation      # Infection, MSI under a 95 % gate
 ```
 
 The supported runtime is PHP `^8.4`. Tests that exercise newer-PHP syntax
 (e.g. the 8.5 pipe operator) are tagged `@group php85`; `make test/unit`
 excludes them and they self-skip via `#[RequiresPhp]` off an 8.5 host. CI
 runs them in a dedicated PHP 8.5 job.
 
+The `xphp check` PHPStan-pass tests are tagged `@group phpstan` — they shell out
+to a real phpstan subprocess (slow), so `make test/unit` excludes them and they
+self-skip when `vendor/bin/phpstan` is absent (the same self-skip idea as
+`@group php85`). CI runs them in a dedicated job; locally use `make
+test/phpstan-pass`. (Not to be confused with `make lint/phpstan`, which runs
+PHPStan over `src/`.)
+
 No PHP 8.5 locally? Run them in the bundled 8.5 container:
 
 ```bash
@@ -21,4 +29,11 @@ docker compose run --rm php85 make test/unit/php85
 
 CI gates every PR on these targets. `infection.json5` carries a curated set
 of per-mutator `ignore` rules for genuinely-equivalent / defensive
-mutations so the report only surfaces real test gaps.
+mutations so the report only surfaces real test gaps.
+
+## Architecture decisions
+
+Architecturally significant decisions — the ones that are expensive to reverse —
+are recorded as [Architecture Decision Records](docs/adr/README.md). When you make
+such a decision, add a new ADR under `docs/adr/` (copy
+[`docs/adr/0000-adr-template.md`](docs/adr/0000-adr-template.md)).

Makefile

@@ -7,11 +7,19 @@
 # targets here.
 
 .PHONY: test/unit
-# Default runtime is PHP 8.4 (composer requires ^8.4). Tests exercising
-# newer-PHP syntax are tagged `@group php85` and excluded here; they run
-# on an 8.5 runtime via `make test/unit/php85`.
+# Default runtime is PHP 8.4 (composer requires ^8.4). Two groups are excluded
+# here: `php85` (newer-PHP syntax; runs on 8.5 via `make test/unit/php85`) and
+# `phpstan` (the `xphp check` PHPStan pass, which shells out to a real phpstan
+# subprocess and is slow; runs via `make test/phpstan-pass`).
 test/unit:
-	php vendor/bin/phpunit --exclude-group php85
+	php vendor/bin/phpunit --exclude-group php85 --exclude-group phpstan
+
+.PHONY: test/phpstan-pass
+# The `xphp check` PHPStan-integration tests (tagged `@group phpstan`). They
+# shell out to the consumer's phpstan binary and self-skip when vendor/bin/phpstan
+# is absent. NOTE: distinct from `lint/phpstan`, which runs PHPStan over src/.
+test/phpstan-pass:
+	php vendor/bin/phpunit --group phpstan
 
 .PHONY: test/unit/php85
 # Runs only the PHP 8.5-specific syntax tests (e.g. the pipe operator).
@@ -35,6 +43,15 @@ lint/phpstan:
 test/mutation:
 	php -d memory_limit=-1 vendor/bin/infection --show-mutations=max --threads=max --min-covered-msi=95
 
+.PHONY: test/check
+# End-to-end self-test of the `check` gate: runs the real bin/xphp binary
+# against the check fixtures and asserts the 0/1/2 exit contract plus that the
+# text/json/github renderers all emit. Reused by release.yml against the built
+# PHAR (override XPHP_BIN="php dist/xphp.phar"). Complements the in-process
+# CheckCommandTest, which can't observe the shipped binary's process exit code.
+test/check:
+	sh test/smoke/check.sh
+
 # Humbug Box is the standard tool for compiling a Composer-managed
 # PHP project into a single self-contained PHAR.  Pinned to a known-
 # good release (Box 4.6.6 supports PHP 8.4) so a new Box version

README.md

@@ -143,6 +143,47 @@ compile. `dist/` holds your rewritten code; `.xphp-cache/Generated/`
 holds the specialized classes. Both can be gitignored and rebuilt
 in CI.
 
+For a real project — and **required** once you consume another package's
+generics — drop an `xphp.json` manifest at the project root instead of
+repeating the paths on every invocation:
+
+```json
+{
+  "sources": ["src"],
+  "include": ["vendor/**"],
+  "target": "dist",
+  "cache": ".xphp-cache"
+}
+```
+
+Then `compile`/`check` take no positional source — they resolve the
+manifest (auto-detected in the working directory, or via `--config`):
+
+```bash
+vendor/bin/xphp compile        # compiles this package + every included one
+vendor/bin/xphp check
+```
+
+`include` globs auto-discover installed xphp packages (`vendor/**` finds
+every one, at any depth, with no edit when you add another), so the
+downstream build compiles the whole union into its own output. See
+[Getting started](docs/getting-started.md#the-recommended-project-setup-an-xphpjson-manifest)
+for the distribution model. The single-directory form above keeps working
+unchanged.
+
+To validate generics without emitting anything — a CI gate that reports
+every bound/variance/etc. problem with a `file:line`:
+
+```bash
+vendor/bin/xphp check src            # exit 1 if any error; --format=text|json|github
+```
+
+`check` runs all of xphp's generic validation (the specialization-loop guards
+aside) and then, when those pass, runs **your** PHPStan over the compiled output
+and maps the findings back to the `.xphp` template — one config, one gate (pass
+`--no-phpstan` to skip it). You still run `compile` to emit the PHP. See
+[Errors and diagnostics](docs/errors.md#xphp-check--validate-without-emitting).
+
 ## See also
 
 - [Getting started](docs/getting-started.md) -- full walkthrough including PSR-4 details, runtime semantics, and what the generated PHP looks like

composer.json

@@ -25,7 +25,8 @@
     "require": {
         "php": "^8.4.0",
         "nikic/php-parser": "^5.7",
-        "symfony/console": "^8.0"
+        "symfony/console": "^8.0",
+        "symfony/process": "^8.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^13.0",