phpstan-base.neon ignores every unknown OCA\OpenRegister class, fleet-wide

[rubenvdlinde]

What was measured

hydra-gates/quality-config/phpstan-base.neon carries these under ignoreErrors:

- '#unknown class OCA\\OpenRegister\\#'
- '#OCA\\OpenRegister\\[a-zA-Z\\]+.*not found#'
- '#on an unknown class OCA\\OpenRegister\\#'
- '#has invalid return type OCA\\OpenRegister\\#'
- '#has invalid type OCA\\OpenRegister\\#'
- '#implements unknown interface OCA\\OpenRegister\\#'

Every leaf app includes this base. So a green phpstan has never been evidence
that any OpenRegister type resolves, in any app. If a leaf app typehints a
contract that does not exist, has been renamed, or has drifted, phpstan reports
nothing and exits 0.

Found while cleaning up the register-slug resolver adoption on buildiq, shillinq
and hermiq. shillinq's phpstan happened to be looking at real files through
scanDirectories; buildiq's and hermiq's never were, and all three were equally
green.

The root cause underneath it

conduction/hydra-gates ships hydra-gates/contracts/ but its composer.json
declares no autoload section at all. So nothing in that directory is
autoloadable by a consumer, which is why every app needs some private mechanism
to see the contracts: an ignoreErrors entry, a scanDirectories entry, a
psalm referencedClass suppression, a local stub copy, or a hand-written
require_once in a test bootstrap. Five mechanisms across the fleet, for one
package that could declare the mapping once.

Measured on buildiq: deleting the referencedClass suppression for
ObjectEntityInterface, which the package has shipped since long before
v1.17.0, makes psalm exit 2. A tagged release was never what made these
resolvable.

Two remedies, one of which is already in use

1. Give the package an autoload entry for OCA\OpenRegister\Contract\.
   This is the one that would let the fleet-wide phpstan ignores go. It needs
   care: hydra-gates claims OCA\OpenRegister\Contract\ as a RUNTIME psr-4 prefix, so any app vendor can define another app contract #531 removed a runtime psr-4 prefix for this exact
   namespace because the prefix is longer than openregister's own, so a vendored
   copy in any app defined the contract for the whole process. An
   analysis-only autoload entry is not obviously the same defect, but it is
   adjacent to it and deserves a real decision rather than a quick patch.

2. List the contract files as psalm <stubs>. Available today, no package
   change. decidesk and pipelinq already do it. buildiq, shillinq and hermiq
   have now adopted it too, in chore(deps-dev): take hydra-gates 1.18.0 and drop the tag-gap workarounds buildiq#741,
   chore(deps-dev): take hydra-gates 1.18.0 and drop the copied contracts shillinq#1567 and chore(deps-dev): take hydra-gates 1.18.0 and drop the tag-gap workarounds hermiq#841, which removed ten
   referencedClass suppressions between them.

Remedy 2 does nothing for phpstan. The ignoreErrors block above is still
there, still fleet-wide, and still means phpstan green says nothing about
OpenRegister types.

Why this is worth acting on rather than noting

A referencedClass suppression makes every value flowing through the contract
mixed, so the analyser stops checking the branch the contract exists to force.
On decidesk, swapping suppressions for stubs surfaced a real nullable that had
shipped. The phpstan ignores are the same shape at fleet scale, and nothing has
looked behind them yet.

🤖 Generated with Claude Code

[rubenvdlinde]

A second analyser blind spot, measured while verifying this one, and the same class of problem: a check that is not running looks exactly like a check that passed.

PossiblyNull* is INFO at errorLevel="4", so psalm exits 0 on it

Measured on decidiq. A deliberate violation, ?string passed to a parameter typed string:

INFO: PossiblyNullArgument - lib/Service/VotingBehaviourService.php:136:29
      Argument 1 of ...::needsString cannot be null, possibly null value provided

composer psalm exit code: 0.

The same tree carries 13 pre-existing PossiblyNull* findings today, all invisible to the exit code, including three PossiblyNullReference on getUID() in EIDASSignatureController.

Why this is worth pinning down rather than filing as noise

It bounds a claim I made earlier in this work and had generalised too far. While proving that psalm stubs beat referencedClass suppressions, I established that NullableReturnStatement is a hard ERROR at errorLevel="4" — measured, reproducible, and the basis for saying the stubs give real checking. That is true.

What is NOT true is the generalisation "psalm catches nullable misuse at level 4". It catches some kinds. At the same errorLevel, in the same app, on the same psalm 5.26.1:

issue	at errorLevel 4	fails the build
NullableReturnStatement	ERROR	yes
PossiblyNullArgument	INFO	no
PossiblyNullReference	INFO	no

A reviewer caught this on shillinq before I did, and was right to. Recording it here because the fleet-level version of the mistake is to read one measured severity as evidence about a family of rules.

It compounds with a per-app suppression

ConductionNL/shillinq also carries a blanket <UndefinedMethod errorLevel="suppress"/> in psalm.xml, added for cross-app event classes. Verified as the only app of the five checked (buildiq, decidiq, hermiq, pipelinq, shillinq) that does this.

The consequence is worth stating plainly: in shillinq's lib/, psalm can fail on neither a call to a method that does not exist, nor a possibly-null argument. That combination defeated a mutation test outright. The standard probe for "is this stub actually live", calling $resolution->noSuchMethodAtAll() and expecting UndefinedMethod, returns silence there, and silence is indistinguishable from a working stub. It took three attempts to establish that shillinq's stub was in fact live, and only @psalm-trace settled it. Filed separately as ConductionNL/shillinq#1569.

The practical ask

Not "raise errorLevel to 1 everywhere" — that would surface a large inherited backlog at once and get reverted. Two cheaper things:

1. Know which rules are load-bearing. A per-app note saying which issue types actually fail the build, so nobody reads a green psalm run as broader assurance than it is.
2. Prefer a probe whose negative result is unambiguous. @psalm-trace reports the inferred type directly and cannot be suppressed into silence, so it distinguishes "psalm agrees" from "psalm was told not to mention it". A probe that relies on an issue being raised is only as good as that issue not being suppressed.

Same shape as the phpstan ignore this issue is about. Both mean an analyser has been quietly narrowed and its green is doing less work than the person reading it believes.