fix(quality): decompose the voting cluster (18 phpmd findings)

[rubenvdlinde]

What

Clears the PHPMD findings remaining in the voting cluster by decomposition — no suppressions, no baseline entries, no threshold changes.

⚠️ Read this first: the baseline, and a stale base

The baseline. decidesk/phpmd.baseline.xml suppresses findings, and PHPMD auto-discovers a file of that name in the working directory whether or not --baseline-file is passed — so a plain phpmd run in the repo root reports a false clean. Every number below was measured with the baseline bypassed via an explicit empty baseline:

docker run --rm -v "$PWD":/app -v /tmp/pmdempty:/pmdempty:ro -w /app php:8.3-cli \
  php vendor/bin/phpmd lib text phpmd.xml --baseline-file /pmdempty/empty-baseline.xml

The stale base. This branch was originally cut from 36985fa6, which turned out not to be an ancestor of development: #380 landed in between and had already decomposed the same voting code. Of the 18 findings this branch was scoped to, #380 already cleared 15. The first version of this branch would have reverted #380's work wholesale (CONFLICTING, 307 files). It has been rebased onto current development; the superseded version is preserved in full on wip/preserve-20260804-d1-voting-facade.

So this PR is scoped to the 3 findings #380 left behind.

	before	after
repo-wide true findings (baseline bypassed)	7 (exit 2)	4 (exit 2)

A line-by-line diff of the before/after reports shows no new finding anywhere in lib/. phpmd.baseline.xml is untouched; with it in place the CI job is still exit 0.

Before → after, per finding

file	finding	before	after
lib/Service/VotingService.php	class CouplingBetweenObjects	20 / 13	9
lib/Service/VotingService.php	closeVotingRound() BooleanArgumentFlag $anonymise	present	gone
lib/Controller/VotingController.php	class CouplingBetweenObjects	19 / 13	11

Also, as a side effect of the facade: VotingService drops from 732 to 372 lines and its overall complexity from 26 to 11.

Already cleared by #380 (verified on current development, not re-done here)

VotingService ExcessiveClassLength / ExcessiveClassComplexity, castVote() Cyclomatic + NPath 3,133,440 + length, both castVote ElseExpressions, closeVotingRound() Cyclomatic + NPath + length, getPublicState() Cyclomatic + NPath, and all three VotingBehaviourService::getStats() findings. 15 in total.

How

VotingService becomes a thin facade — every public operation delegates one line to a single-purpose collaborator. #380's collaborators (VoteCastingService, VotingRoundCloser, VotingRoundProjection, VoteCastGuard, VoteBallotFactory, VoterTokenSecret) are kept exactly as they are and are now injected rather than constructed inside VotingService — which is what actually removed the coupling. Nextcloud auto-wires all of them.

New classes (all in lib/Service/, all with the repo's full docblock + SPDX header)

• VotingRoundOpener — checkQuorum() and openVotingRound(), the last two large methods still inline in VotingService.
• VotingRoundResults — the ballot tally, the show-of-hands tally, and the rule-aware result computation they share.
• ParticipantUuidLookup — Nextcloud UID → participant UUID.
• SavedObjectNormaliser — the ObjectEntity → array normalisation that was duplicated across the moved methods.
• VotingErrorResponder — the exception → HTTP status mapping. This is what takes the controller under the coupling threshold: with the mapping behind a callable, VotingController needs no catch clauses at all, dropping its references to \RuntimeException, \InvalidArgumentException, \Throwable and LoggerInterface. Each endpoint keeps its exact previous status contract by choosing a method — badRequest(), badRequestOrNotFound(), invalidOrMissing(), internalError().
• VotingOpenRequestHandler — the open-a-round request shape (parser + VotingRoundRules assembly + service call), removing VotingOpenRequestParser and VotingRoundRules from the controller.

VotingController also now takes VotingRoundGuard and ProxyDelegationService by injection instead of building them, which drops IGroupManager, IAppConfig, ParticipantResolver and ContainerInterface from its constructor.

BooleanArgumentFlag

closeVotingRound(string $id, bool $anonymise = false, ?string $chairCasting = null) is replaced by two named methods:

• closeVotingRound(string $id, ?string $chairCasting = null)
• closeVotingRoundAnonymised(string $id, ?string $chairCasting = null)

Both delegate to a shared private closeRound(), which preserves the load-bearing order (casting vote persisted → tally reads it → round stamped closed) and calls #380's VotingRoundCloser::close() unchanged. Anonymisation is irreversible, so it is now explicit at every call site. VotingController::close() selects the variant from the request flag in one private method; the HTTP contract is unchanged.

Inline suppressions

None. No @SuppressWarnings, no baseline entries, no psalm/phpstan baseline, no phpmd.xml threshold change.

Verification

Host PHP is 8.2 and vendor/bin/* exits 255 printing nothing there, so every tool ran in a container; exit codes and stderr byte counts were checked on each run.

gate	command	result
phpmd (baseline bypassed)	phpmd lib text phpmd.xml --baseline-file <empty>	exit 2, 7 → 4 findings, 0 bytes stderr
phpmd (committed baseline, CI's view)	phpmd lib text phpmd.xml --baseline-file phpmd.baseline.xml	exit 0, 0 findings
phpunit	phpunit --no-coverage	800 tests, 0 failures, 37 skipped — baseline held
phpcs	phpcs --standard=phpcs.xml	exit 0
psalm	psalm --threads=1 --no-cache	exit 0
phpstan	phpstan analyse --memory-limit=1G	exit 0

Behaviour

No behaviour change is intended. Every exception message, every ObjectService call order, every relation-filter sequence, every fail-soft/fail-closed decision and every response status is preserved verbatim. The 7 VotingService unit-test construction sites and the VotingController one were updated to assemble the collaborator graph that production gets from Nextcloud's auto-wiring.

Not touched (outside this PR's file scope)

• lib/Service/VotingBehaviourService.php still carries 11 @spec anchors pointing at openspec/changes/p2-motion-and-voting-core-t2/, an archived change directory that no longer exists — every one of those anchors is dead. The canonical target is openspec/specs/member-voting-behaviour-tracking/spec.md. Its PHPMD findings were cleared by fix(quality): clear PHPMD architectural debt in decidesk (73 → 7) #380, so the file is no longer in this PR's scope; flagging it for whoever owns it next.
• lib/Repair/InitializeSettings.php and lib/Service/BoardEvaluationResponseService.php carry comments referring to VotingService::voterTokenSecret(), which fix(quality): clear PHPMD architectural debt in decidesk (73 → 7) #380 moved to VoterTokenSecret::value(). Behaviour is unchanged (same app-config key, same HMAC); only the comments are stale.

[github-actions]

Quality Report — ConductionNL/decidesk @ 926797e

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
composer			✅	✅ 100/100
npm			✅	✅ 549/549
PHPUnit					✅
Newman					❌
Playwright					⏭️

---

Quality workflow — 2026-08-04 01:26 UTC

Download the full PDF report from the workflow artifacts.

[rubenvdlinde]

CI note: quality / Integration Tests (Newman) and its downstream quality / Quality Report fail on this PR — and they fail identically on development itself (runs 30868542272 and 30868539257, same two jobs, same 29-job total). Pre-existing, not caused by this change.

Every other job passes, including PHP Quality (phpmd), (phpcs), (psalm), (phpstan) and all four PHPUnit legs. Job count is 29 on both this PR and development, so the gates genuinely ran.