[core] Fix #5039: Refactor RuleContext to use builder pattern #6260

oowekyala · 2025-11-25T14:07:29Z

Describe the PR

Add new API to RuleContext to report violations. The goal is to replace the set of addViolation* methods with a more flexible 2-stage builder pattern. This allows specifying the violation location and the message parameters independently and increases the readability and usability of this API.

I removed the more complex overloads already in this PR (those that were marked @Experimental) and replace their usages. Should we deprecate the simpler methods now, later, never? I think we should do so, but maybe in a separate PR.

API Changes

New Experimental APIs

core
- Node#atLocation
- Node#atToken
- CannotBeSuppressed

Removed Experimental APIs

core
- RuleContext#addViolationWithPosition(Node node, JavaccToken token, String message, Object... formatArgs) (introduced in 7.17.0)
- RuleContext#addViolationWithPosition(Reportable reportable, AstInfo<?> astInfo, FileLocation location, String message, Object... formatArgs) (introduced in 7.9.0)
- RuleContext#addViolationNoSuppress(Reportable reportable, AstInfo<?> astInfo, String message, Object... formatArgs) (introduced in 7.14.0)

Deprecated APIs

core
- RuleContext#addViolationWithPosition(Node node, int beginLine, int endLine, String message, Object... formatArgs)

Related issues

Fix [core] Add fluent API to report violations #5039

Ready?

Added unit tests for fixed bug/feature
Passing all unit tests
Complete build ./mvnw clean verify passes (checked automatically by github actions)
Added (in-code) documentation (if needed)
Update release notes with deprecations

This will replace the many `addViolation*` methods with a simpler set of orthogonal methods. - First specify the location. - Then specify the message/format arguments. Fix pmd#5039

This has been a TODO for a long time. Compared to automatically finding the suppression node, this saves time, as we don't have to explore the whole tree when reporting something.

parse default message ahead of time

pmd-actions-helper · 2025-11-26T18:16:00Z

Documentation Preview

Compared to main:
This changeset changes 18 violations,
introduces 3 new violations, 0 new errors and 0 new configuration errors,
removes 3 violations, 0 errors and 0 configuration errors.

Regression Tester Report

(comment created at 2025-11-29 16:37:01+00:00 for c343925)

Header comments are not considered part of the root node...

adangel

Thanks, I like the new API (almost 😄 )

I would really name the verb report() instead of warn().

If we introduce the new API with the violation builder without marking it Experimental (like it is right now in this PR), then I'd deprecate all the old methods addViolation... right now. No need to wait, because we have then already a stable alternative API.

I've created an "API Changes" section in the description of this PR to keep track of the changes for the release notes so far.

We also need to update the documentation then on how to report a violation: https://docs.pmd-code.org/latest/pmd_userdocs_extending_writing_java_rules.html#reporting-violations

...apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/design/ExcessiveParameterListRule.java

...apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/internal/AbstractCounterCheckRule.java

pmd-core/src/main/java/net/sourceforge/pmd/reporting/RuleContext.java

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java

adangel · 2026-01-08T15:42:50Z

pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/Node.java

+     */
+    @Experimental
+    default Reportable atLocation(FileLocation loc) {
+        assert NodeFindingUtil.nodeCoversLocation(this, loc) : "Node does not contain location " + loc;


Should we always check this condition? assert would only be enabled during unit tests...

I think, it would be better to always check this and throw this as a IllegalArgumentException. If we don't check this, we allow to create confusing violations - maybe better to prevent that at the first place?
Performance wise I think, it should not be too bad: This method would only be called, when a rule is about to report a violation, wouldn't it?

I think this is the kind of assertion that should only be enabled during unit tests. It is relatively expensive to check and will likely be caught by rule unit tests immediately if you used it wrong. And also, nothing bad will happen if this condition is not checked at runtime: no code relies on this assumption being true. Maybe it is completely useless to check this tbh... I just wanted to prevent obvious mistakes by a rule implementor.

It's true it would be only called when reporting a violation but there are already sort of "generic" rules like AbstractCounterCheckRule that use it every time they report something. Those can be used to report metrics (with a very low report level) and therefore report may produce many violations...

pmd-core/src/main/java/net/sourceforge/pmd/reporting/RuleContext.java

adangel · 2026-01-08T16:12:35Z

pmd-core/src/main/java/net/sourceforge/pmd/reporting/RuleContext.java

+     * @since 7.20.0
+     */
+    @CheckReturnValue
+    public ViolationBuilder atLine(int lineNumber) {


Should we really provide this method? It sounds to me a bit lower level. Do you use this method already in some rules?
Used in

CommentContentRule (java)
CommentSizeRule (java)
AvoidTabCharacterRule (plsql)
LineLengthRule (plsql)

Only 4 rules need this. I'd prefer not to provide this as an API, so that there is only one way to create a violation from a rule context. This keeps the API surface smaller.

I think it's a case of "only 4 rules need this for now"... These 4 rules could actually apply to all languages and so we could add rules that use it in the future. It's also a method that is not obvious to implement and which therefore, I think, belongs in a shared API (even if "only" 4 rules need it).

If you want we can make it @Experimental, but this is also an easy to specify method so I don't think there is anything we would need to change about it.

pmd-core/src/main/java/net/sourceforge/pmd/reporting/RuleContext.java

adangel · 2026-01-08T16:23:26Z

pmd-core/src/main/java/net/sourceforge/pmd/reporting/RuleContext.java

+    private final RootNode rootNode;
+
+    // Default message, parsed only once to avoid overhead of parsing.
+    private MessageFormat defaultMessageFormat;


Is it worth it? A new RuleContext is created for every file and rule. The message would only be reused, if the same rule finds more than one violation in a single file...

adangel · 2026-01-08T16:24:15Z

pmd-core/src/main/java/net/sourceforge/pmd/reporting/RuleContext.java

+
+    /** Marker annotation for Intellij inspection to warn on unused return value. */
+    @Documented
+    @interface CheckReturnValue {


We probably should move this annotation to net.sourceforge.pmd.annotation.

Or did you mean to use com.google.errorprone.annotations.CheckReturnValue? We get it currently transitively via com.google.code.gson:gson, but if we use it ourselves, we should at a explicit dependency.

The intellij inspection handles any annotation called CheckReturnValue. It doesn't even need to be public (which is why I kept this annotation package private). If we really want to use a well-known annotation then I would suggest using jetbrains annotations instead, because that package is small and would give us @NotNull/@Nullable (#6134).

oowekyala · 2026-01-13T13:00:23Z

If we introduce the new API with the violation builder without marking it Experimental (like it is right now in this PR), then I'd deprecate all the old methods addViolation... right now. No need to wait, because we have then already a stable alternative API.

Are you ok with doing this in a companion PR? I would prefer this PR to be only about the new API and the other being just mechanical translation.

oowekyala added 8 commits November 25, 2025 14:40

Refactor RuleContext to use builder pattern

122c254

This will replace the many `addViolation*` methods with a simpler set of orthogonal methods. - First specify the location. - Then specify the message/format arguments. Fix pmd#5039

Make RuleContext store current RootNode

c0073d0

Deprecate some of the old methods

c751c8f

Add CannotBeSuppressed to remove addViolationNoSuppress

229fb8b

Doc

2cdbeb2

Rename method warn with args for clarity

6b7e3de

Reorder methods

4be2325

Replace more usages

4f0da64

oowekyala added this to the 7.20.0 milestone Nov 25, 2025

oowekyala mentioned this pull request Nov 25, 2025

[java] Add new rule SimplifyStreamExpression #5725

Draft

4 tasks

oowekyala added 8 commits November 26, 2025 15:24

Add method to Reportable to find suppression node

b7077f1

This has been a TODO for a long time. Compared to automatically finding the suppression node, this saves time, as we don't have to explore the whole tree when reporting something.

Doc

ce8fec2

Use interface CannotBeSuppressed properly

a63cbb8

Doc

1a85393

Merge branch 'main' into issue5039-rulecontext-fluent-api

62eb948

Fix UnnecessaryPmdSuppression tests

6be2978

Fix plsql tests

5840844

Delete deprecated experimental methods,

1679c63

parse default message ahead of time

oowekyala marked this pull request as ready for review November 26, 2025 22:57

oowekyala added the an:enhancement An improvement on existing features / rules label Nov 27, 2025

oowekyala mentioned this pull request Nov 27, 2025

[java] Shrink reported locations for some rules #6084

Draft

3 tasks

oowekyala added 3 commits November 27, 2025 14:02

Fix PLSQL LineLength reported on wrong line

eb374bb

Header comments are not considered part of the root node...

Merge branch 'main' into issue5039-rulecontext-fluent-api

2c0442c

Merge branch 'main' into issue5039-rulecontext-fluent-api

c343925

adangel modified the milestones: 7.20.0, 7.21.0 Dec 30, 2025

oowekyala requested a review from jsotuyod January 5, 2026 11:44

adangel requested changes Jan 8, 2026

View reviewed changes

adangel changed the title ~~[core] Refactor RuleContext to use builder pattern~~ [core] Fix #5039: Refactor RuleContext to use builder pattern Jan 8, 2026

oowekyala added 5 commits January 13, 2026 13:10

Merge branch 'main' into issue5039-rulecontext-fluent-api

51aeeaa

Fix review comments

704c235

Rename RuleContext methods warn -> report

020dec6

Use final field for language services

9745354

Update release notes

34a9b74

Update doc on website and improve javadoc

a636cdf

Uh oh!

[core] Fix #5039: Refactor RuleContext to use builder pattern #6260

Are you sure you want to change the base?

[core] Fix #5039: Refactor RuleContext to use builder pattern #6260

Uh oh!

Conversation

oowekyala commented Nov 25, 2025 • edited by adangel Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe the PR

API Changes

New Experimental APIs

Removed Experimental APIs

Deprecated APIs

Related issues

Ready?

Uh oh!

pmd-actions-helper bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adangel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oowekyala commented Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

oowekyala commented Nov 25, 2025 •

edited by adangel

Loading

pmd-actions-helper bot commented Nov 26, 2025 •

edited

Loading