feat(flags): add semver targeting to local evaluation

src/PostHog/Api/ComparisonOperator.cs

@@ -103,5 +103,59 @@ public enum ComparisonOperator
     /// Matches if the flag condition evaluates to the specified value.
     /// </summary>
     [JsonStringEnumMemberName("flag_evaluates_to")]
-    FlagEvaluatesTo
+    FlagEvaluatesTo,
+
+    /// <summary>
+    /// Matches if the version exactly equals the filter version.
+    /// </summary>
+    [JsonStringEnumMemberName("semver_eq")]
+    SemverEquals,
+
+    /// <summary>
+    /// Matches if the version does not equal the filter version.
+    /// </summary>
+    [JsonStringEnumMemberName("semver_neq")]
+    SemverNotEquals,
+
+    /// <summary>
+    /// Matches if the version is greater than the filter version.
+    /// </summary>
+    [JsonStringEnumMemberName("semver_gt")]
+    SemverGreaterThan,
+
+    /// <summary>
+    /// Matches if the version is greater than or equal to the filter version.
+    /// </summary>
+    [JsonStringEnumMemberName("semver_gte")]
+    SemverGreaterThanOrEquals,
+
+    /// <summary>
+    /// Matches if the version is less than the filter version.
+    /// </summary>
+    [JsonStringEnumMemberName("semver_lt")]
+    SemverLessThan,
+
+    /// <summary>
+    /// Matches if the version is less than or equal to the filter version.
+    /// </summary>
+    [JsonStringEnumMemberName("semver_lte")]
+    SemverLessThanOrEquals,
+
+    /// <summary>
+    /// Matches if the version is within the tilde range (~X.Y.Z means >=X.Y.Z and &lt;X.Y+1.0).
+    /// </summary>
+    [JsonStringEnumMemberName("semver_tilde")]
+    SemverTilde,
+
+    /// <summary>
+    /// Matches if the version is within the caret range (^X.Y.Z is compatible-with per semver spec).
+    /// </summary>
+    [JsonStringEnumMemberName("semver_caret")]
+    SemverCaret,
+
+    /// <summary>
+    /// Matches if the version matches the wildcard pattern (e.g., "1.2.*" means >=1.2.0 and &lt;1.3.0).
+    /// </summary>
+    [JsonStringEnumMemberName("semver_wildcard")]
+    SemverWildcard
 }

src/PostHog/Features/LocalEvaluator.cs

@@ -584,6 +584,15 @@ bool MatchProperty(PropertyFilter propertyFilter, string distinctId, Dictionary<
             ComparisonOperator.IsSet => true, // We already checked to see that the key exists.
             ComparisonOperator.IsDateBefore => value.IsDateBefore(overrideValue, _timeProvider.GetUtcNow()),
             ComparisonOperator.IsDateAfter => !value.IsDateBefore(overrideValue, _timeProvider.GetUtcNow()),
+            ComparisonOperator.SemverEquals => value.CompareSemver(overrideValue) == 0,
+            ComparisonOperator.SemverNotEquals => value.CompareSemver(overrideValue) != 0,
+            ComparisonOperator.SemverGreaterThan => value.CompareSemver(overrideValue) > 0,
+            ComparisonOperator.SemverGreaterThanOrEquals => value.CompareSemver(overrideValue) >= 0,
+            ComparisonOperator.SemverLessThan => value.CompareSemver(overrideValue) < 0,
+            ComparisonOperator.SemverLessThanOrEquals => value.CompareSemver(overrideValue) <= 0,
+            ComparisonOperator.SemverTilde => value.IsSemverTildeMatch(overrideValue),
+            ComparisonOperator.SemverCaret => value.IsSemverCaretMatch(overrideValue),
+            ComparisonOperator.SemverWildcard => value.IsSemverWildcardMatch(overrideValue),
             null => true, // If no operator is specified, just return true.
             _ => throw new InconclusiveMatchException($"Unknown operator: {propertyFilter.Operator}")
         };

src/PostHog/Json/PropertyFilterValue.cs

@@ -6,6 +6,7 @@
 using PostHog.Api;
 using PostHog.Library;
 using static PostHog.Library.Ensure;
+using static PostHog.Library.SemanticVersion;
 
 namespace PostHog.Json;
 
@@ -254,6 +255,91 @@ or DateOnly
     public static bool operator >=(PropertyFilterValue left, object? right) => NotNull(left).CompareTo(right) >= 0;
     public static bool operator <=(PropertyFilterValue left, object? right) => NotNull(left).CompareTo(right) <= 0;
 
+    static SemanticVersion ParseOverrideSemver(object? overrideValue)
+    {
+        var overrideVersionString = overrideValue?.ToString();
+        if (!SemanticVersion.TryParse(overrideVersionString, out var version))
+        {
+            throw new InconclusiveMatchException($"Cannot parse override value '{overrideVersionString}' as a semantic version");
+        }
+        return version.Value;
+    }
+
+    SemanticVersion ParseFilterSemver()
+    {
+        if (!SemanticVersion.TryParse(StringValue, out var version))
+        {
+            throw new InconclusiveMatchException($"Cannot parse filter value '{StringValue}' as a semantic version");
+        }
+        return version.Value;
+    }
+
+    /// <summary>
+    /// Compares the override value as a semantic version against this filter value.
+    /// </summary>
+    /// <param name="overrideValue">The version value from person/group properties.</param>
+    /// <returns>A comparison result: negative if override &lt; filter, zero if equal, positive if override &gt; filter.</returns>
+    /// <exception cref="InconclusiveMatchException">Thrown if either value cannot be parsed as a valid semver.</exception>
+    public int CompareSemver(object? overrideValue)
+    {
+        var overrideVersion = ParseOverrideSemver(overrideValue);
+        var filterVersion = ParseFilterSemver();
+        return overrideVersion.CompareTo(filterVersion);
+    }
+
+    /// <summary>
+    /// Checks if the override value is within the tilde range specified by this filter value.
+    /// ~X.Y.Z means >=X.Y.Z and &lt;X.Y+1.0
+    /// </summary>
+    /// <param name="overrideValue">The version value from person/group properties.</param>
+    /// <returns><c>true</c> if the override version is within the tilde range.</returns>
+    /// <exception cref="InconclusiveMatchException">Thrown if either value cannot be parsed as a valid semver.</exception>
+    public bool IsSemverTildeMatch(object? overrideValue)
+    {
+        var overrideVersion = ParseOverrideSemver(overrideValue);
+        var filterVersion = ParseFilterSemver();
+        var (lower, upper) = filterVersion.GetTildeBounds();
+        return overrideVersion.IsInRange(lower, upper);
+    }
+
+    /// <summary>
+    /// Checks if the override value is within the caret range specified by this filter value.
+    /// ^X.Y.Z is compatible-with per semver spec:
+    /// - ^1.2.3 means >=1.2.3 &lt;2.0.0 (major > 0)
+    /// - ^0.2.3 means >=0.2.3 &lt;0.3.0 (major = 0, minor > 0)
+    /// - ^0.0.3 means >=0.0.3 &lt;0.0.4 (major = 0, minor = 0)
+    /// </summary>
+    /// <param name="overrideValue">The version value from person/group properties.</param>
+    /// <returns><c>true</c> if the override version is within the caret range.</returns>
+    /// <exception cref="InconclusiveMatchException">Thrown if either value cannot be parsed as a valid semver.</exception>
+    public bool IsSemverCaretMatch(object? overrideValue)
+    {
+        var overrideVersion = ParseOverrideSemver(overrideValue);
+        var filterVersion = ParseFilterSemver();
+        var (lower, upper) = filterVersion.GetCaretBounds();
+        return overrideVersion.IsInRange(lower, upper);
+    }
+
+    /// <summary>
+    /// Checks if the override value matches the wildcard pattern specified by this filter value.
+    /// "X.*" or "X" means >=X.0.0 &lt;X+1.0.0
+    /// "X.Y.*" means >=X.Y.0 &lt;X.Y+1.0
+    /// </summary>
+    /// <param name="overrideValue">The version value from person/group properties.</param>
+    /// <returns><c>true</c> if the override version matches the wildcard pattern.</returns>
+    /// <exception cref="InconclusiveMatchException">Thrown if either value cannot be parsed.</exception>
+    public bool IsSemverWildcardMatch(object? overrideValue)
+    {
+        var overrideVersion = ParseOverrideSemver(overrideValue);
+
+        if (!TryParseWildcard(StringValue, out var lower, out var upper))
+        {
+            throw new InconclusiveMatchException($"Cannot parse filter value '{StringValue}' as a wildcard pattern");
+        }
+
+        return overrideVersion.IsInRange(lower.Value, upper.Value);
+    }
+
     public override string ToString()
     {
         return this switch