perf: Analyze rules before running to limit context [DHIS2-21245]

[enricocolasante]

Summary

Adds a static analysis pass (RuleEngineAnalyzer) that inspects program rules and their variables before evaluation to determine the minimum context data required. The result is surfaced as a new RuleContextRequirements value object in the public API, giving callers (e.g. dhis2-core) enough information to skip fetching data they don't need.

Jira: DHIS2-21245

---

Changes

New API

• RuleContextRequirements — immutable data class (in api/ package) with five
  fields:

  • needsAllEvents — true when the ruleset references multi-event variables (RuleVariableNewestEvent, RuleVariableNewestStageEvent, RuleVariablePreviousEvent) or the V{event_count} env var.
  • needsEnrollment — true when enrollment env vars (enrollment_date, enrollment_id, enrollment_count, enrollment_status, incident_date, tei_count) or TEI attributes are referenced.
  • needsDataValues — true when any event data-value variable type is referenced.
  • needsAttributes — true when RuleVariableAttribute is referenced.
  • orgUnitGroups — set of group UIDs appearing in d2:inOrgUnitGroup() calls across all rule conditions and action data expressions.

• RuleEngine.analyzeContextRequirements(rules, variables): RuleContextRequirements — new method on the public interface, delegating to RuleEngineAnalyzer.

• RuleContextRequirementsJs + RuleEngineJs.analyzeContextRequirements(…) — JS wrapper exposing the same feature to the JS target (uses Array<String> for orgUnitGroups as required by @JsExport).

Housekeeping

• RuleEngineUtils constants sorted alphabetically.
• Dead helper isAllowedAction removed from RuleEventUtils (logic already inlined in Rule).
• Version bumped 3.7.2-SNAPSHOT → 3.8.0-SNAPSHOT (breaking interface change).
• expressionParser dependency bumped 1.4.0 → 1.4.1 (provides collectInOrgUnitGroups on Expression).

[vgarciabnz]

Good! This was a missing piece in the rule engine API.
The performance benefit is on the context gathering part, isn't it? So if a client doesn't fetch the requirements in the first place and just uses the rule engine as before, the rule engine will continue to keep working as usual but there wouldn't be performance improvement, is it right? So this is an "optional" feature, it is not directly breaking the clients, right?

[vgarciabnz]

Maybe you want to add an annotation here to avoid having to write RuleContextRequirements.Companion.getNONE() in Java.

I think that you could get:

• with @JvmStatic -> RuleContextRequirements.getNONE()
• with @JvmField -> RuleContextRequirements.NONE

[enricocolasante]

I actually changed it to internal.
This object is only used as a response and shouldn't really be created in the client.

[enricocolasante]

Good! This was a missing piece in the rule engine API. The performance benefit is on the context gathering part, isn't it? So if a client doesn't fetch the requirements in the first place and just uses the rule engine as before, the rule engine will continue to keep working as usual but there wouldn't be performance improvement, is it right? So this is an "optional" feature, it is not directly breaking the clients, right?

Yes, this feature is optional and it is not breaking the client.

[superskip]

I had a brief look and have a couple of questions: First, is it primarily the backend that is going to make use of this? I can see Capture web app potentially being able to skip some of the conversion steps with this, but probably not any api calls (as we don't make any of those within the rule engine).

The second question is about a technical detail, please see comment below 👇

[superskip]

Nice! 🎉

[vgarciabnz]

This data class could be shared (JS+JVM), unless you prefer to leave it separately just in case we want to add something here that is not compatible with JVM.

[enricocolasante]

You are right. It was in here before because we had an Array

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
76.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud