PLUGINAPI-190 Promote hidden to a first-class flag on PropertyDefinition

[steve-marion-sonarsource]

WHY:

The current plugin-api exposes hidden, setScope, and setOnlyScope. However, the effect of hidden is limited and only covers hiding the global variable when defined with scope. It is unusable with a scope. Internally, it is dropped, and its effect comes through the global flag, which disables showing the parameter at the instance level when no scope is defined.
This is against the initial intention described in MMF-339.

WHAT:

Add support for hiding properties independently from their scoped or global definition.
Keep backward compatibility with existing definitions.

HOW:

Keep the hidden value as defined by the builder, and set global to represent whether the property is intended to be configured at the global level.
hidden now has the meaning of hiding the property from the UI by not listing it.
global now has the meaning of allowing get/edit of properties at the instance level.
This allows simplifying the code by removing checks on global and scope that were carrying the hidden meaning before.

A backward-compatible translation is put in place for the legacy @Property(global = false, scope=[]) idiom. It is auto-translated to hidden = true, global = true, configScopes = [] which keep the behavior intact. The annotation itself is intentionally not extended with a hidden field, as it is already considered legacy and the builder should be used instead.

Current behavior — truth table

Builder input			valid?	Resulting state		Effect (no component)		Effect (comp = X)
.hidden()	.onConfigScopes(X)	.onlyOnConfigScopes(X)		global	configScopes	listed	settable	listed	settable
–	–	–	✅	true	[]	✅	✅	❌	❌
✅	–	–	✅	false	[]	❌	✅ (via isGlobal fallback)	❌	❌
–	✅	–	✅	true	[X]	✅	✅	✅	✅
–	–	✅	✅	false	[X]	❌	❌	✅	✅
✅	✅	–	❌	—	—	—	—	—	—
✅	–	✅	❌	—	—	—	—	—	—
–	✅	✅	❌	—	—	—	—	—	—
✅	✅	✅	❌	—	—	—	—	—	—

Proposed behavior — truth table

Builder input			valid?	Resulting state			Effect (no component)		Effect (comp = X)
.hidden()	.onConfigScopes(X)	.onlyOnConfigScopes(X)		hidden	global	configScopes	listed	settable	listed	settable
–	–	–	✅	false	true	[]	✅	✅	❌	❌
✅	–	–	✅	true	true	[]	❌ (via !hidden)	✅	❌	❌
–	✅	–	✅	false	true	[X]	✅	✅	✅	✅
–	–	✅	✅	false	false	[X]	❌	❌	✅	✅
✅	✅	–	✅ (newly allowed)	true	true	[X]	❌ (via !hidden)	✅	❌ (via !hidden)	✅
✅	–	✅	✅ (newly allowed)	true	false	[X]	❌ (via !hidden)	❌	❌ (via !hidden)	✅
–	✅	✅	❌	—	—	—	—	—	—	—
✅	✅	✅	❌	—	—	—	—	—	—	—

[hashicorp-vault-sonar-prod]

PLUGINAPI-190

[sonar-review-alpha]

Summary

⚠️ The PR description exceeded the analysis limit and was truncated. The review may not reflect all context.

This PR promotes hidden from an implicit side effect to a first-class flag on PropertyDefinition, decoupling visibility from global/scope configuration. Previously, hidden was only settable via the builder but had no field and was immediately overridden; the PR fixes this by storing the hidden flag directly and using it to determine UI visibility independently of the global flag.

A backward-compatibility translation is built into the annotation parser: the legacy pattern @Property(global = false, scopes=[]) is auto-converted to hidden=true, global=true, configScopes=[], preserving existing behavior. Importantly, the @Property annotation itself is not extended with a hidden field—it remains legacy-only and developers should use the builder for new code.

The validation rule preventing hidden + scopes is removed; you can now hide a property at any scope configuration, which was previously impossible.

What reviewers should know

Start by reviewing:

1. The annotation translation logic in PropertyDefinition.create() (lines 192-207) — this is where backward compatibility lives. The comments explain what each combination means.
2. The new hidden() getter (lines 359-365) — straightforward but critical for the API.
3. The removed validation and global-overriding code (around line 670-673) — these constraints no longer apply.

Key decisions to verify:

• The legacy idiom translation only triggers for global=false with empty scopes. This is the narrow case that represents "hidden but settable at instance level."
• The hidden field is initialized from builder.hidden in the constructor, ensuring the builder's intent is preserved (this was the bug before).
• Removed tests that enforced !hidden || no scopes; now hidden properties can have any scope config. The new tests (lines 99-138) validate all combinations work.

Watch for:

• The backward-compatibility translation assumes existing code using @Property(global=false) with no scopes was trying to hide properties. If real-world plugins use this pattern for a different reason, behavior changes.
• Tests replace old negative cases with new positive ones—make sure all old constraints are actually obsolete and the new behavior is documented elsewhere (e.g., in Javadoc or MMF-339).

---

• Generate Walkthrough
• Generate Diagram

🗣️ Give feedback

[steve-marion-sonarsource]

Dropping this change.

[sonarqube-next]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
0 Dependency risks
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

[lukasz-jarocki-sonarsource]

Well done!

[sonar-review-alpha]

The new commit is a one-line comment correction ("not visible but settable at scope only" → "visible and settable at scope only"). No logic was changed. The previously flagged concern about @Beta on the new hidden() getter and Builder.hidden() is still open.

🗣️ Give feedback

[sonarqube-next]

Quality Gate passed

Issues
0 New issues
0 Fixed issues
0 Accepted issues

Measures
0 Security Hotspots
0 Dependency risks
88.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube

[aleksandra-bozhinoska-sonarsource]

Looks good to me!