Repository navigation
Description
Summary
gate-3 (stub-scan), rule caller-identity-ignored, reports three findings on ConductionNL/procest for which no correct app-side fix exists. The parameter it objects to is an interface-contract obligation, and the interface's other implementors genuinely use it.
This is the same family as the interface-declaration false positive already fixed in #291 — but one step further along: #291 covered bodiless declarations, and this is an implementation with a real body that correctly does not need the parameter.
The findings
lib/Service/Transitions/ChecklistGuard.php:65 method=evaluate rule=caller-identity-ignored param=$userId
lib/Service/Transitions/RequiredDocumentGuard.php:50 method=evaluate rule=caller-identity-ignored param=$userId
lib/Service/Transitions/RequiredFieldGuard.php:48 method=evaluate rule=caller-identity-ignored param=$userId
Why there is no fix the author can make
All three implement one interface:
// lib/Service/Transitions/GuardEvaluatorInterface.php:47
public function evaluate(array $guardConfig, array $case, string $userId): GuardResult;There are five implementors, and $userId references inside evaluate():
| implementor | $userId refs |
uses caller identity? |
|---|---|---|
RoleGuard |
12 | yes — this is the whole point of the class |
MandaatGuard |
3 | yes |
ChecklistGuard |
1 (signature only) | no — inspects the case's checklist |
RequiredDocumentGuard |
1 (signature only) | no — inspects the case's documents |
RequiredFieldGuard |
1 (signature only) | no — inspects a case field |
A guard that asks "is this required field filled in?" has no business consulting the caller. The three flagged classes are correct. The only ways to silence the gate are:
- delete the parameter — breaks
GuardEvaluatorInterfaceand every call site inGuardRegistry::evaluateAll(); or - reference
$userIdpointlessly in the body to get the grep count to 2 — i.e. write dead code to satisfy a stub detector.
Both make the code worse. Neither is something a reviewer should accept.
The signal the gate is walking past
All three already carry an explicit, reason-bearing marker that the parameter is deliberately unused:
* @param string $userId Current user UID (unused)
*
* @SuppressWarnings(PHPMD.UnusedFormalParameter)That is the house convention for exactly this situation, it is already enforced elsewhere (PHPMD reads it), and gate-3 does not look at it.
Suggested fix
In the caller-identity-ignored loop in run-hydra-gates.sh, skip a method when either holds:
- the docblock immediately preceding the signature carries
@SuppressWarnings(PHPMD.UnusedFormalParameter), or - the
@paramline for the flagged parameter carries an explicit unused/ignored marker.
The first is preferable: it is an existing, tool-enforced annotation rather than a new gate-specific opt-out, so it cannot be sprinkled around freely without PHPMD agreeing.
Please guard the change with a planted true positive: a service method that takes $userId, ignores it, and carries no suppression must still be reported. An exemption that cannot fail is worth less than the finding it removes.
Impact
3 findings on procest. Fleet-wide this pattern will appear anywhere a strategy/guard/handler interface passes caller identity to implementors that do not all need it, which is a normal shape.
Activity
rubenvdlinde commentedon Aug 13, 2026
Reproduced and fixed in #434.
Reproduction first. Full 60-gate run on a fresh
developmentcheckout of six fleet apps (hydra-gates@c26f9a3). procest792fe1f4b: 3 findings, the same three files and the same parameter. opencatalogi, openregister, softwarecatalog, docudesk, larpingapp: 0 each. The issue is months old and this one re-runs exactly as filed.The premise holds. I tried to write the closing action and could not. Deleting
$userIdbreaksGuardEvaluatorInterfaceand every call site inGuardRegistry::evaluateAll(); referencing it to push the grep count to 2 is dead code written to satisfy a stub detector. There was no third option.The fix. New
check_caller_identity_exempt.py. A finding is exempt only when both hold:implements/extends, transitively). Fully mechanical, nothing asserted. This is what makes the exemption un-sprinklable: an invented service method has no supertype, so it cannot be silenced by a docblock edit.@paramline for that parameter carries an explicit unused marker.Condition 1 alone would exempt a genuinely gutted implementation — a
RoleGuardthat stopped consulting$userIdis contract-imposed too, and that is the defect the rule exists for. Condition 2 alone is a one-word escape hatch.On the
@SuppressWarnings(PHPMD.UnusedFormalParameter)suggestion — I took the stricter of the two options you offered, and the measurement is why. That annotation is method-wide and cannot name which parameter it excuses.MandaatGuardcarries it (for a different parameter) while genuinely using$userId; keying on it would have pre-authorised MandaatGuard's$userIdfor a reason that was never about$userId. The per-@parammarker is per-parameter, and all three findings already carry it, so no app-side edit is required — procest's code is untouched.Fail-closed: missing helper, unreadable file, or a supertype outside this repository all leave the finding standing.
The planted true positive you asked for — five arms, four of them controls (
test_gate_3_contract_param.sh):Arms 2–5 each delete exactly one half of the exemption. Revert test: the same suite against
origin/main's unmodified runner — arm 1 goes red, all four controls stay green, so they were never depending on the fix.Effect: procest 3 → 0 across a full 60-gate run, runner exit 8 → 7, and gate-3 is the only verdict line that moved. 0 → 0 on the other five apps.
fix(gates): gate-3 spares a contract-imposed unused param; gate-53 co…
test(gate-3): pin the #434 exemption against the #422 mask — the two …
fix(quality): the skip gate must read `fixme` annotations too (#561)