Docs workspace on the current satellites, rector in CI, two generator fixes

.github/workflows/docs.yml

@@ -5,12 +5,12 @@ name: docs
 # is reflected out of all five `src/` trees at build time.
 #
 # Pull requests build and check but never deploy. `master` deploys. The
-# reference documents the satellites from their PUBLISHED tags: a satellite
-# release changes what belongs on this site without changing a single file
-# here. Deliberately no `repository_dispatch` wired to a satellite release —
-# a cross-repository PAT for a rare event that the weekly cron already bounds
-# is not worth the secret-management overhead; `workflow_dispatch` covers the
-# "I want it now" case by hand.
+# reference documents the satellites at the versions
+# `docs/.api-workspace/composer.lock` holds — a caret on 0.x pins a minor, so
+# the lock moves in the release PR that follows a satellite release, and the
+# `composer outdated` step below turns a lock left behind into a red build
+# rather than a site that quietly documents a version three minors old (which
+# is what happened between 2026-08-28 and 2026-09-05).
 on:
   pull_request:
     paths: &paths
@@ -29,7 +29,8 @@ on:
     branches:
       - master
     paths: *paths
-  # The reference is never more than a week behind an adapter release.
+  # The weekly run re-reads the lock, so a satellite release nobody pinned is
+  # reported within a week even when nothing here changed.
   schedule:
     - cron: '41 5 * * 1' # Mondays, 05:41 UTC
   workflow_dispatch:
@@ -83,6 +84,13 @@ jobs:
         working-directory: docs/.api-workspace
         run: composer install --no-interaction --no-progress
 
+      # A satellite with a release the pins do not reach is documented at the
+      # wrong version, silently. `--direct` looks at the four satellites only
+      # (and the docblock parser, ignored), `--strict` makes it a red build.
+      - name: Refuse a workspace that documents a satellite behind its release
+        working-directory: docs/.api-workspace
+        run: composer outdated --direct --strict --ignore phpdocumentor/reflection-docblock
+
       # What every engine reference page is stamped with. On a tagged commit
       # `git describe` prints the tag; between releases it prints the nearest
       # tag plus the commit, so a page built from master still says which

.github/workflows/static-analysis.yml

@@ -85,3 +85,10 @@ jobs:
 
       - name: Psalm
         run: composer psalm
+
+      # Part of `composer release-check`, and until now run by nobody but a
+      # human before a tag: rector was red under green builds for five
+      # releases of this family before anyone looked. Same job, so the
+      # required check keeps its name.
+      - name: Rector
+        run: composer rector

.gitignore

@@ -1,5 +1,8 @@
 vendor/
 composer.lock
+# The API reflection workspace is a project, not a library: its lock is what
+# the site documents the satellites from, and it moves with their releases.
+!/docs/.api-workspace/composer.lock
 .php-cs-fixer.cache
 /build/*
 !/build/.gitkeep

AGENTS.md

@@ -451,6 +451,7 @@ decided lives in this section and in `docs/scripts/check-integrity.mjs`.
 | **A new `@api` free function needs `make docs-api` too**, and a row in `llms.txt` | checks 2b and 7 — the class-only pipeline used to drop functions silently |
 | **A new PHPStan rule needs its row on `/api/rules` in the same PR** | check 9; the analyser packages have no other public contract |
 | **`MIGRATION.md` is generated** from `docs/src/guide/migrating-*.md`. Edit the pages, run `make docs-migration` | check via `docs:check:migration` |
+| **`docs/.api-workspace/composer.lock` is committed and moves with every satellite release.** A caret on 0.x pins a minor, so `^0.2` documented `understudy-psalm` 0.2.0 while 0.8.0 was out; bump the pin, `composer update` in the workspace, `make docs-api`, commit all three | `docs.yml` runs `composer outdated --direct --strict` there and goes red otherwise |
 | **`make perf` means re-reading three files**: `perf/README.md`, `README.md`'s Performance table and `README.ru.md`'s. Keep the `<!-- #region site -->` markers and the `Taken YYYY-MM-DD` line | checks 10 and 11 |
 | **An `@include` that cannot resolve fails silently in VitePress** — the page renders as its heading and nothing else | check 12 |
 | **`{{` in prose needs `<code v-pre>`** | Vue interpolates it otherwise |

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## Unreleased
+
+- **The API reference documents the satellites at their current versions.**
+  `docs/.api-workspace/composer.json` pinned `understudy-psalm ^0.2`,
+  `understudy-phpstan ^0.2`, `understudy-phpunit ^0.1` and `understudy-testo
+  ^0.1` — a caret on 0.x pins a minor — so the site reflected the plugins at
+  0.2.0 and the adapters at 0.1.x while 0.8.0, 0.5.0, 0.2.0 and 0.3.0 were out,
+  and the weekly rebuild rebuilt the same thing. The pins move to the current
+  lines, the workspace lock is committed so the pages in the repository and on
+  the site come from the same install, and `docs.yml` runs `composer outdated
+  --direct --strict` in the workspace: a satellite release the pins do not
+  reach is a red build now, not a stale page.
+- `static-analysis.yml` runs `composer rector` in the Psalm job. It is part of
+  `composer release-check` and was run by nobody but a human before a tag —
+  this package went out four times with it red under green builds.
+- Two defects of the reference generator that the refresh exposed:
+  `docs/scripts/reflect-rules.php` took every string literal starting with
+  `understudy.` for a rule identifier, so `ClosureShape`'s php-parser attribute
+  `understudy.receiverOfCall` sat on the rules page as a sixth identifier nobody
+  could write into `ignoreErrors` (only constants named `*IDENTIFIER` count
+  now); and `generate-api.mjs` had no label for a trait, so the PHPUnit
+  adapter's page was headed «undefined».
+
 ## 0.9.0 — 2026-09-05
 
 The 1.0 candidate. A minor rather than a patch, and the last one before the

docs/.api-workspace/composer.json

@@ -5,18 +5,18 @@
     "require": {
         "php": "8.3 - 8.5",
         "phpdocumentor/reflection-docblock": "^5.6",
-        "rasuvaeff/understudy-phpstan": "^0.2",
-        "rasuvaeff/understudy-phpunit": "^0.1",
-        "rasuvaeff/understudy-psalm": "^0.2",
-        "rasuvaeff/understudy-testo": "^0.1"
+        "rasuvaeff/understudy-phpstan": "^0.5",
+        "rasuvaeff/understudy-phpunit": "^0.3",
+        "rasuvaeff/understudy-psalm": "^0.8",
+        "rasuvaeff/understudy-testo": "^0.3"
     },
     "repositories": [
         {
             "type": "path",
             "url": "../..",
             "options": {
                 "versions": {
-                    "rasuvaeff/understudy": "0.4.0"
+                    "rasuvaeff/understudy": "0.9.0"
                 }
             }
         }