Add fuzzy/proximity search test coverage and docs for issue #182

Closes #182

Made-with: Cursor

Author: niemyjski

src/Foundatio.Parsers.LuceneQueries/Nodes/IQueryNode.cs

@@ -88,6 +88,12 @@ public interface IFieldQueryWithProximityAndBoostNode : IFieldQueryNode
     /// <summary>
     /// The proximity/slop factor (~) for fuzzy or phrase proximity searches.
     /// </summary>
+    /// <remarks>
+    /// Non-null when the tilde (~) operator is present.
+    /// For unquoted terms (e.g., <c>roam~0.8</c>), this indicates a fuzzy search with edit distance.
+    /// For quoted terms (e.g., <c>"jakarta apache"~10</c>), this indicates a phrase proximity search with word slop.
+    /// An empty string means the bare tilde was used with no explicit value (e.g., <c>term~</c>).
+    /// </remarks>
     string Proximity { get; set; }
 
     /// <summary>

tests/Foundatio.Parsers.LuceneQueries.Tests/QueryParserTests.cs

@@ -1,4 +1,4 @@
-#define ENABLE_TRACING
+#define ENABLE_TRACING
 
 using System;
 using System.Threading.Tasks;
@@ -516,6 +516,62 @@ public async Task CanGenerateSingleQueryAsync()
         await new AssignOperationTypeVisitor().AcceptAsync(result, null);
         _logger.LogInformation("{Result}", await DebugQueryVisitor.RunAsync(result));
     }
+
+    [Theory]
+    [InlineData("term~", null, false, "")]
+    [InlineData("term~1", null, false, "1")]
+    [InlineData("roam~0.8", null, false, "0.8")]
+    [InlineData("\"phrase query\"~2", null, true, "2")]
+    [InlineData("field:term~", "field", false, "")]
+    [InlineData("field:\"phrase\"~3", "field", true, "3")]
+    public void Parse_WithProximityModifier_SetsProximityOnTermNode(string query, string expectedField, bool expectedQuoted, string expectedProximity)
+    {
+        var parser = new LuceneQueryParser();
+        var result = parser.Parse(query);
+
+        _logger.LogInformation("{Result}", DebugQueryVisitor.Run(result));
+        string generatedQuery = GenerateQueryVisitor.Run(result);
+        Assert.Equal(query, generatedQuery);
+
+        var termNode = result.Left as TermNode;
+        Assert.NotNull(termNode);
+        Assert.Equal(expectedField, termNode.Field);
+        Assert.Equal(expectedQuoted, termNode.IsQuotedTerm);
+        Assert.Equal(expectedProximity, termNode.Proximity);
+    }
+
+    [Fact]
+    public void Parse_WithFuzzyTermInGroup_SetsProximityOnInnerTermNode()
+    {
+        var parser = new LuceneQueryParser();
+        var result = parser.Parse("searchKeywords:(\"Wellness\"~)");
+
+        _logger.LogInformation("{Result}", DebugQueryVisitor.Run(result));
+        string generatedQuery = GenerateQueryVisitor.Run(result);
+        Assert.Equal("searchKeywords:(\"Wellness\"~)", generatedQuery);
+
+        var groupNode = result.Left as GroupNode;
+        Assert.NotNull(groupNode);
+        Assert.Equal("searchKeywords", groupNode.Field);
+        Assert.True(groupNode.HasParens);
+
+        var termNode = groupNode.Left as TermNode;
+        Assert.NotNull(termNode);
+        Assert.Equal("Wellness", termNode.Term);
+        Assert.True(termNode.IsQuotedTerm);
+        Assert.Equal("", termNode.Proximity);
+    }
+
+    [Fact]
+    public void Parse_WithoutProximityModifier_ProximityIsNull()
+    {
+        var parser = new LuceneQueryParser();
+        var result = parser.Parse("field:value");
+
+        var termNode = result.Left as TermNode;
+        Assert.NotNull(termNode);
+        Assert.Null(termNode.Proximity);
+    }
 }
 
 public class TestQueryVisitor : ChainableQueryVisitor

tests/Foundatio.Parsers.LuceneQueries.Tests/QueryParserValidationTests.cs

@@ -1,4 +1,4 @@
-#define ENABLE_TRACING
+#define ENABLE_TRACING
 
 using System;
 using System.Threading.Tasks;
@@ -65,6 +65,11 @@ public QueryParserValidationTests(ITestOutputHelper output) : base(output)
     [InlineData("roam~0.8")]
     [InlineData("criter^2")]
     [InlineData("\"blah criter\"~1")]
+    [InlineData("field:(\"Wellness\"~)")]
+    [InlineData("field:(\"Wellness\"~2)")]
+    [InlineData("field:\"Wellness\"~")]
+    [InlineData("field:Wellness~")]
+    [InlineData("field:Wellness~2")]
     [InlineData("count:>1")]
     [InlineData(@"book.\*:test")]
     [InlineData("count:>=1")]