async-test-lib/pmd-ruleset.xml at main · PIsberg/async-test-lib · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<?xml version="1.0"?>
<ruleset name="async-test-lib PMD ruleset"
         xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
    <description>
        Quickstart ruleset with intentional architectural exclusions documented below.
    </description>

    <rule ref="rulesets/java/quickstart.xml">
        <!--
            AvoidUsingVolatile: Volatile fields are an intentional thread-safety design choice
            throughout the detector infrastructure (e.g. ThreadLeakDetector, LicenseGuard).
            The CLAUDE.md thread_safe_elements section documents each strategy.
        -->
        <exclude name="AvoidUsingVolatile"/>

        <!--
            ControlStatementBraces: Builder.java is a generated validation class with hundreds
            of single-statement guard clauses. Enforcing braces there would bloat the file
            significantly without improving readability or safety.
        -->
        <exclude name="ControlStatementBraces"/>

        <!--
            ClassNamingConventions: Classes like SimpleDateFormat_, CountDownLatch_, CyclicBarrier_
            etc. use an underscore suffix intentionally to signal they are adapter/proxy wrappers
            of the standard Java class with the same base name.
        -->
        <exclude name="ClassNamingConventions"/>

        <!--
            AvoidCatchingGenericException: six sites, all deliberate.

            Five are in ConcurrencyRunner (lines 429, 723, 726, 735 and 742), which must catch
            Throwable to propagate assertion failures and errors from worker threads back to the
            test thread; narrowing to Exception would silently swallow AssertionError and
            OutOfMemoryError. PMD 7.26.0 reports these under this rule, and its message on
            ConcurrencyRunner:429 is literally "Avoid catching Throwable in try-catch block",
            because AvoidCatchingThrowable is no longer a separate rule in the quickstart ruleset.
            Excluding that name as well only produced a PMD warning ("Exclude pattern
            'AvoidCatchingThrowable' did not match any rule"), so it was removed; if a future PMD
            reintroduces it, the sites above are the ones to re-argue.

            The sixth is genuinely generic: AsyncTestAgent.selfAttach:236 catches
            `RuntimeException | Error` around ByteBuddyAgent.install(). That is also deliberate:
            install() fails in several unchecked ways and the catch exists to rethrow all of them as
            the IllegalStateException naming -Djdk.attach.allowAttachSelf=true.
        -->
        <exclude name="AvoidCatchingGenericException"/>

        <!--
            AvoidAccessibilityAlteration: ConcurrencyRunner uses reflection (setAccessible) to
            invoke test methods on the test instance directly. This is the standard JUnit 5
            extension mechanism for custom test runners and cannot be avoided.
        -->
        <exclude name="AvoidAccessibilityAlteration"/>

        <!--
            InstantiableUtilityClass / MissingStaticMethodInNonInstantiatableClass:
            AsyncAssert and ConcurrencyRunner are public classes whose implicit constructor is
            part of the published API; a private one would be a binary-incompatible change. PMD
            7.28.0 renamed UseUtilityClass to InstantiableUtilityClass and
            left the old name as a deprecated reference that an exclude no longer matches.
        -->
        <exclude name="InstantiableUtilityClass"/>
        <exclude name="MissingStaticMethodInNonInstantiatableClass"/>

        <!--
            AvoidThreadGroup: ThreadGroup usage is intentional for capturing uncaught-exception
            scope in the UncaughtExceptionHandlerDetector.
        -->
        <exclude name="AvoidThreadGroup"/>

        <!--
            AvoidBranchingStatementAsLastInLoop: The break-as-last-in-loop pattern is used
            intentionally in search loops where the loop condition cannot encode the termination.
        -->
        <exclude name="AvoidBranchingStatementAsLastInLoop"/>

        <!--
            CloseResource: ExecutorService and ScheduledExecutorService instances flagged here are
            shut down explicitly via shutdownNow() in finally blocks. SpotBugs covers resource leaks
            with higher fidelity and also runs in the verify phase.
        -->
        <exclude name="CloseResource"/>

        <!--
            GuardLogStatement: This rule was designed for log frameworks that evaluate string
            arguments eagerly (e.g. "val: " + obj). The project uses SLF4J parameterized logging
            (log.warn("{}", x)) which defers toString() until the message is actually consumed —
            so if(log.isWarnEnabled()) guards add boilerplate with no performance benefit.
        -->
        <exclude name="GuardLogStatement"/>
    </rule>
</ruleset>