Skip to content

fix(phpmd): scope the lib/Migration UnusedFormalParameter exclusion to its own ruleset - #132

Closed
rubenvdlinde wants to merge 2 commits into
developmentfrom
fix/phpmd-unusedparams-ruleset
Closed

rubenvdlinde wants to merge 2 commits into
developmentfrom
fix/phpmd-unusedparams-ruleset

Conversation

@rubenvdlinde

@rubenvdlinde rubenvdlinde commented Aug 5, 2026 •

Copy link
Copy Markdown
Contributor

Part of the fleet PHPMD ruleset fix (ConductionNL/.github#155). Propagates the shape
already merged in nextcloud-app-template #125, doriath #157, larpingapp #263 and planix #315.

The defect

phpmd.xml declared:

<rule ref="rulesets/unusedcode.xml/UnusedFormalParameter">
    <exclude-pattern>*Migration*</exclude-pattern>
</rule>

A nested <exclude-pattern> is inert. PHPMD 2.15 reads exclude-patterns in
RuleSetFactory::getIgnorePattern(), which walks $xml->children() — only elements
directly under <ruleset>. A nested one parses without error and is discarded, so
lib/Migration was scanned by the very rule the pattern was written to spare.

Reproduced directly on this repo's ruleset: a probe class in lib/Migration with three
unused formal parameters was reported, exit 2, with the nested pattern in place.

Why not simply hoist the pattern

A top-level <exclude-pattern> is applied by PDepend's ExcludePathFilter at
file-collection time, so it drops the file from every rule in the ruleset — real
complexity, StaticAccess and method-length findings in migrations would silently vanish.

The shape shipped here

  • phpmd.xml no longer declares UnusedFormalParameter; a comment records why.
  • New phpmd-unusedparams.xml holds that rule alone, with a top-level
    */Migration/* exclude — so the exclusion is scoped to that one rule and nothing else.
  • The phpmd composer script runs both legs, keeping the worst exit code so neither
    leg can short-circuit the other.

Why lib/Migration is exempt from this one rule: OCP\Migration\IMigrationStep mandates
changeSchema(IOutput $output, Closure $schemaClosure, array $options) and
preSchemaChange/postSchemaChange with the same three parameters. A step that needs none
of them still cannot drop them — the signature is not ours to change.

Measurement

PHPMD 2.15.0 (the version this repo's lockfile pins) on PHP 8.4.22, run in a
nextcloud:latest container: host PHP 8.2 makes vendor/bin/phpmd die in
platform_check.php with exit 255, which reads exactly like a clean run. Exit codes
are read directly, never through a pipe. Findings are compared as normalised
path:line:rule triples — PHPMD right-pads the file:line column in text output, so raw
line diffs are meaningless.

findings leg exits
reported, before 0 leg1=0
reported, after 0 leg1=0 leg2=0
true (every @SuppressWarnings stripped on a throwaway copy), before 211 leg1=2
true, after 211 leg1=2 leg2=2

The true count strips every @SuppressWarnings in lib/ on a throwaway copy that is
never committed
, so the comparison isolates the ruleset change from the suppressions.

Retired: 0

Newly appearing (true): 0 — must be 0, and is.
Newly appearing (reported): 0. Retired (reported): 0.

Zero newly-hidden findings: every triple present before is present after, except the
retired UnusedFormalParameter hits inside lib/Migration listed above.

lib/Migration in this repo: 0 PHP file(s).

Dead-gate proof

A new leg that exits 0 on the shipped tree is indistinguishable from a leg that does not
run. Proven otherwise on a throwaway copy (probes removed before committing) — three
probes, run through the shipped two-leg invocation:

probe expected observed
lib/Migration/ZzProbeMigration.php UnusedFormalParameter dropped not reported
lib/Migration/ZzProbeMigration.php ElseExpression still live reported, leg 1
lib/ZzProbe/ZzProbe.php UnusedFormalParameter still live reported, leg 2
leg1=2
leg2=2
leg1	lib/Migration/ZzProbeMigration.php:6:ElseExpression
leg2	lib/ZzProbe/ZzProbe.php:4:UnusedFormalParameter
leg2	lib/ZzProbe/ZzProbe.php:4:UnusedFormalParameter

Leg 2 goes from exit 0 to exit 2 under the probe, so it is live. The Migration
ElseExpression probe is still reported, so isolating the rule did not blind the
other rules to lib/Migration — which is exactly what a hoisted top-level pattern would
have done.

The rig itself was positive-controlled before the first measurement: the same probes under
the unfixed ruleset were reported with exit 2, including the three UnusedFormalParameter
hits in lib/Migration that the nested pattern was supposed to suppress.

Baseline

phpmd.baseline.xml present: yes (174 entries). None was added, deleted or shrunk.

PHPMD auto-discovers phpmd.baseline.xml from the working directory, so removing the
--baseline-file flag would be a no-op — the baseline stays active either way. Verified
empirically on this fleet: identical command, baseline file present → 0 findings / exit 0;
same command with the file absent → 93 findings / exit 2.

Suppressions

0 deleted. This repo has no lib/Migration directory at all, so it carried no @SuppressWarnings(PHPMD.UnusedFormalParameter) tags for this fix to make redundant.

This fix therefore retires nothing in this repo. Its value is the corrected shape — the old nested pattern was inert either way, and the new leg is proven live below. This repo still carries 9 UnusedFormalParameter and 4 other suppressions elsewhere in lib/; those are outside this PR's scope and untouched.

The existing --exclude '*/Resources/template/*' filter is carried through to the new leg so both legs analyse exactly the same file set.

No @SuppressWarnings was added. No threshold was changed, no rule weakened, no baseline
entry added, nothing skipped.

Tests

phpunit -c phpunit-unit.xml:

  • before: 746 tests, 2342 assertions, 1 PHPUnit warning — OK
  • after: 746 tests, 2342 assertions, 1 PHPUnit warning — OK (unchanged)

(The default phpunit.xml suite needs a live Nextcloud runtime and errors out in a bare
checkout — a pre-existing condition this change does not touch.)

What this PR does NOT do

  • does not add or remove a baseline, a @SuppressWarnings, a threshold change or a waiver
  • does not touch any rule other than UnusedFormalParameter
  • does not burn down any of the remaining suppression-free findings — that is separate work

…o its own ruleset

The nested <exclude-pattern> inside the UnusedFormalParameter <rule> was inert:
PHPMD 2.15 honours exclude-patterns only as direct children of <ruleset>, so
lib/Migration was scanned by the very rule the pattern was written to spare.

Hoisting the pattern to the top level of phpmd.xml would have worked but is
applied at file-collection time, dropping lib/Migration from EVERY rule and
silently swallowing real complexity, StaticAccess and method-length findings.

UnusedFormalParameter now lives alone in phpmd-unusedparams.xml with a
top-level */Migration/* exclude, and the phpmd composer script runs both legs
keeping the worst exit code.
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/openbuild @ 51cd315

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
composer ✅ ✅ 101/101
npm ✅ ✅ 654/654
PHPUnit ✅
Newman ⏭️
Playwright ⏭️
Hydra gates ❌

Quality workflow — 2026-08-05 14:34 UTC

Download the full PDF report from the workflow artifacts.

*/Migration/* matches any directory segment named Migration, so it would also
exempt ordinary classes under lib/Service/Migration/ and similar, which have no
interface-mandated signature and must stay analysed. Measured on openconnector,
that broader form hides a genuine UnusedFormalParameter finding in
lib/Service/Migration/. Only the app's own lib/Migration/ holds IMigrationStep
implementations, so only that directory is exempted.

Re-verified after the change: the lib/Migration probe is still excluded, the
non-UnusedFormalParameter Migration probe is still reported by leg 1, and the
retired-finding counts are unchanged.
@github-actions

github-actions Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/openbuild @ c91a580

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
test-l10n ✅
composer ✅ ✅ 101/101
npm ✅ ✅ 654/654
PHPUnit ✅
Newman ⏭️
Playwright ⏭️
Hydra gates ❌

Quality workflow — 2026-08-05 15:01 UTC

Download the full PDF report from the workflow artifacts.

@rubenvdlinde

Copy link
Copy Markdown
Contributor Author

Closing — superseded by #129, whose pattern has been tightened to this PR's shape.

Both PRs address the same fleet defect (the inert nested <exclude-pattern>, ConductionNL/.github#155) and overlap on composer.json, phpmd.xml and phpmd-unusedparams.xml. #129 additionally burns 33 baselined findings (195 → 162) across 15 lib/ files plus two test files, so it is the larger change and the one being landed.

Where this PR was more correct, and the correction has been carried across:

this PR (#132) #129 as written #129 now
exclude-pattern */lib/Migration/* */Migration/* */lib/Migration/*

Worth stating plainly for the record: openbuild has no lib/Migration/ directory — measured against development, zero paths match ^lib/Migration/. The nearest things are lib/Repair/MigrateAppOverridesToHybrid.php and lib/Repair/MigrateToVersionedModel.php, and those are Migrate, not Migration, so neither candidate pattern matches them. Both patterns therefore retire zero findings here, and #129's ruleset already says so honestly in its description.

That makes the narrow form more important here, not less: with no directory to legitimately match, the only thing the broad */Migration/* could ever do in this repo is exclude something by accident. Positive-controlled (PHPMD 2.15.0, PHP 8.4, absolute paths):

probe */lib/Migration/* */Migration/*
unused param in lib/Service/ (control) reported reported
unused param in lib/Migration/ not reported (intended) not reported (intended)
unused param in lib/Service/Migration/ reported silently swallowed

Both PRs pass --exclude '*/Resources/template/*' to both legs, so the analysed file set is unchanged between them on that axis.

Nothing from this PR is lost. Follow #129.

@github-actions github-actions Bot mentioned this pull request Aug 23, 2026
13 tasks done
@github-actions github-actions Bot mentioned this pull request Oct 7, 2026
13 tasks done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant