feat(flags): add semver targeting to local evaluation

[dmarticus]

💡 Motivation and Context

This PR adds semantic versioning (semver) comparison operators to local feature flag evaluation in the PostHog Android SDK. This enables targeting users based on app version using standard semver semantics.

Why this is needed:

• Enables feature flag targeting based on app version (e.g., "enable for users on version >= 2.0.0")
• Aligns Android SDK with existing implementations in:
  • PostHog Python SDK (feat: add semver targeting support to local flag evaluation posthog-python#447)
  • PostHog server (feat(flags): support semver comparisons in user_blast_radius posthog#44596)
• Allows local evaluation of semver-based feature flags without server round-trips

9 semver operators added:

Operator	Example	Meaning
semver_eq	1.2.3	Exact match
semver_neq	1.2.3	Not equal
semver_gt	1.2.3	Greater than
semver_gte	1.2.3	Greater than or equal
semver_lt	1.2.3	Less than
semver_lte	1.2.3	Less than or equal
semver_tilde	~1.2.3	Patch-level range (>=1.2.3 <1.3.0)
semver_caret	^1.2.3	Compatible-with range (>=1.2.3 <2.0.0)
semver_wildcard	1.2.*	Wildcard range (>=1.2.0 <1.3.0)

💚 How did you test it?

Unit tests added (25+ test cases in FlagEvaluatorTest.kt):

• Basic comparison operators: testSemverEq, testSemverNeq, testSemverGt, testSemverGte, testSemverLt, testSemverLte
• Range operators:
  • testSemverTilde / testSemverTildeWithZeroMinor — patch-level ranges
  • testSemverCaretMajorGreaterThanZero / testSemverCaretMajorZeroMinorGreaterThanZero / testSemverCaretMajorAndMinorZero — caret range edge cases
  • testSemverWildcardMajorOnly / testSemverWildcardMajorAndMinor — wildcard patterns
• Parsing edge cases:
  • testSemverPartialVersions — "1.2" parsed as "1.2.0"
  • testSemverFourPartVersions — "1.2.3.4" parsed as "1.2.3"
  • testSemverLeadingZeros — "01.02.03" parsed as "1.2.3"
  • v-prefix handling, whitespace trimming, pre-release suffix stripping
• Error handling:
  • testSemverInvalidEmptyString, testSemverInvalidLeadingDot, testSemverInvalidNonNumeric
  • testSemverInvalidConditionValue, testSemverMissingPropertyKey, testSemverNullPropertyValue
• Integration: testSemverInFeatureFlag — full flag evaluation with semver operator

All tests pass locally.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

[github-actions]

posthog-android Compliance Report

Date: 2026-03-04 22:59:13 UTC
Duration: 147084ms

⚠️ Some Tests Failed

17/29 tests passed, 12 failed

---

Capture Tests

⚠️ 17/29 tests passed, 12 failed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	2331ms
Format Validation.Event Has Uuid	✅	2027ms
Format Validation.Event Has Lib Properties	✅	2024ms
Format Validation.Distinct Id Is String	✅	2025ms
Format Validation.Token Is Present	✅	2023ms
Format Validation.Custom Properties Preserved	✅	2023ms
Format Validation.Event Has Timestamp	✅	2019ms
Retry Behavior.Retries On 503	❌	7027ms
Retry Behavior.Does Not Retry On 400	✅	4024ms
Retry Behavior.Does Not Retry On 401	✅	4021ms
Retry Behavior.Respects Retry After Header	❌	7020ms
Retry Behavior.Implements Backoff	❌	17022ms
Retry Behavior.Retries On 500	❌	7018ms
Retry Behavior.Retries On 502	❌	7021ms
Retry Behavior.Retries On 504	❌	7020ms
Retry Behavior.Max Retries Respected	❌	17037ms
Deduplication.Generates Unique Uuids	✅	2039ms
Deduplication.Preserves Uuid On Retry	❌	7025ms
Deduplication.Preserves Uuid And Timestamp On Retry	❌	12027ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	❌	7029ms
Deduplication.No Duplicate Events In Batch	✅	2031ms
Deduplication.Different Events Have Different Uuids	✅	2022ms
Compression.Sends Gzip When Enabled	❌	2018ms
Batch Format.Uses Proper Batch Structure	✅	2017ms
Batch Format.Flush With No Events Sends Nothing	✅	2014ms
Batch Format.Multiple Events Batched Together	✅	2028ms
Error Handling.Does Not Retry On 403	✅	4020ms
Error Handling.Does Not Retry On 413	❌	4019ms
Error Handling.Retries On 408	✅	7025ms

Failures

retry_behavior.retries_on_503

Expected at least 3 requests, got 1

retry_behavior.respects_retry_after_header

Expected at least 2 requests, got 1

retry_behavior.implements_backoff

Expected at least 3 requests, got 1

retry_behavior.retries_on_500

Expected at least 2 requests, got 1

retry_behavior.retries_on_502

Expected at least 2 requests, got 1

retry_behavior.retries_on_504

Expected at least 2 requests, got 1

retry_behavior.max_retries_respected

Expected 4 requests, got 1

deduplication.preserves_uuid_on_retry

Need at least 2 requests to check retry

deduplication.preserves_uuid_and_timestamp_on_retry

Expected at least 3 requests, got 1

deduplication.preserves_uuid_and_timestamp_on_batch_retry

Expected at least 2 requests, got 1

compression.sends_gzip_when_enabled

Header 'Content-Encoding' with value 'gzip' not found in requests

error_handling.does_not_retry_on_413

Expected 1 requests, got 2

[marandaneto]

data class generates a bunch of stuff that you prob dont need here (eg hash, toString, etc)

[marandaneto]

all methods that throw should be annotated with @throws(type...) so the caller knows what to do

[marandaneto]

i think you could do this in a cleaner way with regex
eg

private val SEMVER_RE =
    Regex("""^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.\d+)*?(?:[-+].*)?$""")


private fun parseSemverRegex(version: String): SemverVersion {
    var cleaned = version.trim()
	if (cleaned.startsWith("v", ignoreCase = true)) cleaned = cleaned.substring(1)
    val m = SEMVER_PREFIX_RE.matchEntire(cleaned)
        ?: throw InconclusiveMatchException("Invalid semver version: '$version'")

    val major = m.groupValues[1].toInt()
    val minor = m.groupValues[2].takeIf { it.isNotEmpty() }?.toInt() ?: 0
    val patch = m.groupValues[3].takeIf { it.isNotEmpty() }?.toInt() ?: 0

    return SemverVersion(major, minor, patch)
}

ps: have not tested this, gpt generated, but i remember doing this before so it should work or just small changes needed

[marandaneto]

you also need to release core because theres changes for PostHogLocalEvaluationModels.kt