Skip to content
This repository was archived by the owner on Mar 31, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 28 additions & 2 deletions src/Apollo.Application/ToDos/FuzzyTimeParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,22 @@ public sealed class FuzzyTimeParser : IFuzzyTimeParser
{
private static readonly IReadOnlyList<ITimeExpressionParser> Parsers = DiscoverParsers();

public Result<DateTime> TryParseFuzzyTime(string input, DateTime referenceTimeUtc)
public Result<DateTime> TryParseFuzzyTime(string input, DateTime referenceTimeUtc, string? userTimeZoneId = null)
{
if (string.IsNullOrWhiteSpace(input))
{
return Result.Fail<DateTime>("Input is empty or whitespace");
}

var reference = referenceTimeUtc.Kind == DateTimeKind.Utc
var utcReference = referenceTimeUtc.Kind == DateTimeKind.Utc
? referenceTimeUtc
: DateTime.SpecifyKind(referenceTimeUtc, DateTimeKind.Utc);

var localReference = GetLocalReferenceTime(utcReference, userTimeZoneId);

foreach (var parser in Parsers)
{
var reference = parser is IUsesUtcReferenceTimeExpressionParser ? utcReference : localReference;
var result = parser.TryParse(input, reference);
if (result.IsSuccess)
Comment thread
codeacula marked this conversation as resolved.
Resolved
{
Expand All @@ -60,4 +63,27 @@ private static List<ITimeExpressionParser> DiscoverParsers()
&& t.IsDefined(attributeType, inherit: false))
.Select(t => (ITimeExpressionParser)Activator.CreateInstance(t)!)];
}

private static DateTime GetLocalReferenceTime(DateTime utcReference, string? userTimeZoneId)
{
if (string.IsNullOrWhiteSpace(userTimeZoneId))
{
return utcReference;
}

try
{
var timeZone = TimeZoneInfo.FindSystemTimeZoneById(userTimeZoneId);
var localReference = TimeZoneInfo.ConvertTimeFromUtc(utcReference, timeZone);
return DateTime.SpecifyKind(localReference, DateTimeKind.Unspecified);
}
catch (TimeZoneNotFoundException)
{
return utcReference;
}
catch (InvalidTimeZoneException)
{
return utcReference;
}
}
}
6 changes: 3 additions & 3 deletions src/Apollo.Application/ToDos/Parsers/ClockTimeParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@ private static Result<DateTime> ResolveTimeAlias(string timeStr, DateTime refere

return timeStr switch
{
"noon" => Result.Ok(TimeParserHelpers.EnsureUtc(reference.Date.AddHours(12))),
"midnight" => Result.Ok(TimeParserHelpers.EnsureUtc(reference.Date.AddDays(1))),
"noon" => Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(reference.Date.AddHours(12))),
"midnight" => Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(reference.Date.AddDays(1))),
_ => TimeParserHelpers.ParseTimeOfDay(timeStr) switch
{
{ IsSuccess: true } timeResult => Result.Ok(TimeParserHelpers.EnsureUtc(reference.Date.Add(timeResult.Value))),
{ IsSuccess: true } timeResult => Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(reference.Date.Add(timeResult.Value))),
_ => Result.Fail<DateTime>($"Could not resolve clock time '{timeStr}'")
}
};
Expand Down
4 changes: 2 additions & 2 deletions src/Apollo.Application/ToDos/Parsers/DayOfWeekParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)
{
if (NextWeekPattern().IsMatch(input))
{
return Result.Ok(TimeParserHelpers.EnsureUtc(referenceTimeUtc.AddDays(7)));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(referenceTimeUtc.AddDays(7)));
}

var dayMatch = DayPattern().Match(input);
Expand All @@ -56,6 +56,6 @@ private static Result<DateTime> ResolveDayMatch(Match match, DateTime reference)
}
}

return Result.Ok(TimeParserHelpers.EnsureUtc(date));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(date));
}
Comment thread
codeacula marked this conversation as resolved.
Resolved
}
2 changes: 1 addition & 1 deletion src/Apollo.Application/ToDos/Parsers/DurationParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ namespace Apollo.Application.ToDos.Parsers;
/// "5 minutes", "2 hours".
/// </summary>
[TimeExpressionParser]
public sealed partial class DurationParser : ITimeExpressionParser
public sealed partial class DurationParser : ITimeExpressionParser, IUsesUtcReferenceTimeExpressionParser
{
// "in N unit" — minutes, hours, days, weeks with common abbreviations
[GeneratedRegex(
Expand Down
4 changes: 2 additions & 2 deletions src/Apollo.Application/ToDos/Parsers/EndOfPeriodParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)
{
if (EndOfDayPattern().IsMatch(input))
{
return Result.Ok(TimeParserHelpers.EnsureUtc(referenceTimeUtc.Date.AddHours(17)));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(referenceTimeUtc.Date.AddHours(17)));
}

if (EndOfWeekPattern().IsMatch(input))
Expand All @@ -34,7 +34,7 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)
daysUntilFriday = 7;
}
var endOfWeek = referenceTimeUtc.Date.AddDays(daysUntilFriday).AddHours(17);
return Result.Ok(TimeParserHelpers.EnsureUtc(endOfWeek));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(endOfWeek));
}

return Result.Fail<DateTime>($"'{input}' is not an end-of-period expression");
Expand Down
4 changes: 2 additions & 2 deletions src/Apollo.Application/ToDos/Parsers/TimeOfDayAliasParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)

if (match.Groups["tonight"].Success)
{
return Result.Ok(TimeParserHelpers.EnsureUtc(referenceTimeUtc.Date.AddHours(20)));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(referenceTimeUtc.Date.AddHours(20)));
}

var hours = match.Groups["period"].Value.ToLowerInvariant() switch
Expand All @@ -38,6 +38,6 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)
_ => 12
};

return Result.Ok(TimeParserHelpers.EnsureUtc(referenceTimeUtc.Date.AddHours(hours)));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(referenceTimeUtc.Date.AddHours(hours)));
}
}
7 changes: 7 additions & 0 deletions src/Apollo.Application/ToDos/Parsers/TimeParserHelpers.cs
Original file line number Diff line number Diff line change
Expand Up @@ -69,4 +69,11 @@ internal static DateTime EnsureUtc(DateTime dt)
_ => dt
};
}

internal static DateTime KeepUtcElseUseUnspecified(DateTime dt)
{
return dt.Kind == DateTimeKind.Utc
? dt
: DateTime.SpecifyKind(dt, DateTimeKind.Unspecified);
Comment thread
codeacula marked this conversation as resolved.
Resolved
}
}
6 changes: 3 additions & 3 deletions src/Apollo.Application/ToDos/Parsers/TomorrowParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)
if (timeResult.IsSuccess)
{
var dt = referenceTimeUtc.Date.AddDays(1).Add(timeResult.Value);
return Result.Ok(TimeParserHelpers.EnsureUtc(dt));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(dt));
}
}

Expand All @@ -50,11 +50,11 @@ public Result<DateTime> TryParse(string input, DateTime referenceTimeUtc)
_ => 9
};
var dt = referenceTimeUtc.Date.AddDays(1).AddHours(hours);
return Result.Ok(TimeParserHelpers.EnsureUtc(dt));
return Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(dt));
}

return TomorrowPattern().IsMatch(input)
? Result.Ok(TimeParserHelpers.EnsureUtc(referenceTimeUtc.AddDays(1)))
? Result.Ok(TimeParserHelpers.KeepUtcElseUseUnspecified(referenceTimeUtc.AddDays(1)))
: Result.Fail<DateTime>($"'{input}' is not a tomorrow expression");
}
}
6 changes: 5 additions & 1 deletion src/Apollo.Application/ToDos/TimeParsingService.cs
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ public async Task<Result<DateTime>> ParseTimeAsync(
var now = timeProvider.GetUtcNow().UtcDateTime;

// Step 1: Try FuzzyTimeParser (natural language patterns)
var fuzzyResult = fuzzyTimeParser.TryParseFuzzyTime(input, now);
var fuzzyResult = fuzzyTimeParser.TryParseFuzzyTime(input, now, userTimeZoneId);
if (fuzzyResult.IsSuccess)
{
var utcFuzzy = ConvertToUtc(fuzzyResult.Value, userTimeZoneId);
Expand Down Expand Up @@ -174,5 +174,9 @@ private static DateTime ConvertUnspecifiedToUtc(DateTime parsedDate, string? use
{
return DateTime.SpecifyKind(parsedDate, DateTimeKind.Utc);
}
catch (ArgumentException)
{
return DateTime.SpecifyKind(parsedDate, DateTimeKind.Utc);
}
}
}
7 changes: 4 additions & 3 deletions src/Apollo.Core/ToDos/IFuzzyTimeParser.cs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ public interface IFuzzyTimeParser
/// Attempts to parse a fuzzy time expression.
/// </summary>
/// <param name="input">The input string to parse (e.g., "in 10 minutes", "tomorrow")</param>
/// <param name="referenceTimeUtc">The reference time to calculate relative times from (should be UTC)</param>
/// <returns>A Result containing the parsed UTC DateTime if successful, or failure if the input is not a recognized fuzzy time format</returns>
Result<DateTime> TryParseFuzzyTime(string input, DateTime referenceTimeUtc);
/// <param name="referenceTimeUtc">The UTC reference time used for relative duration expressions.</param>
/// <param name="userTimeZoneId">The user's timezone used to interpret wall-clock expressions like "tomorrow at 3pm".</param>
/// <returns>A Result containing the parsed DateTime if successful, or failure if the input is not a recognized fuzzy time format.</returns>
Result<DateTime> TryParseFuzzyTime(string input, DateTime referenceTimeUtc, string? userTimeZoneId = null);
Comment on lines 11 to +17

Copilot AI Mar 25, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The updated IFuzzyTimeParser contract now allows timezone-aware parsing, but the XML docs still don’t specify what DateTime.Kind callers should expect (UTC vs Unspecified for wall-clock results). Please document the intended Kind semantics explicitly so downstream callers don’t incorrectly assume everything is UTC (the root cause of #193).

Copilot uses AI. Check for mistakes.
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
namespace Apollo.Core.ToDos;

/// <summary>
/// Marks fuzzy time parsers that should evaluate relative expressions against a UTC reference.

Copilot AI Mar 25, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The summary says "Marks fuzzy time parsers" but this marker is used for ITimeExpressionParser implementations. Tweaking the wording here would avoid confusion about whether this applies to IFuzzyTimeParser itself vs individual expression parsers.

Suggested change
/// Marks fuzzy time parsers that should evaluate relative expressions against a UTC reference.
/// Marks time expression parsers that should evaluate relative expressions against a UTC reference.

Copilot uses AI. Check for mistakes.
/// </summary>
public interface IUsesUtcReferenceTimeExpressionParser;
30 changes: 26 additions & 4 deletions tests/Apollo.Application.Tests/ToDos/FuzzyTimeParserTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,35 @@ public void TryParseFuzzyTimePreservesUtcKindFromReference()
}

[Fact]
public void TryParseFuzzyTimeConvertsUnspecifiedKindToUtc()
public void TryParseFuzzyTimeWithTimezoneUsesLocalReferenceForWallClockExpressions()
{
var unspecifiedReference = new DateTime(2025, 12, 30, 12, 0, 0, DateTimeKind.Unspecified);
var utcReference = new DateTime(2025, 12, 30, 1, 30, 0, DateTimeKind.Utc);

var result = _parser.TryParseFuzzyTime("in 10 minutes", unspecifiedReference);
var result = _parser.TryParseFuzzyTime("tomorrow at 3pm", utcReference, "America/Chicago");

Assert.True(result.IsSuccess);
Assert.Equal(DateTimeKind.Utc, result.Value.Kind);
Assert.Equal(new DateTime(2025, 12, 30, 15, 0, 0, DateTimeKind.Unspecified), result.Value);
}

[Fact]
public void TryParseFuzzyTimeWithTimezoneKeepsUtcReferenceForDurations()
{
var utcReference = new DateTime(2025, 12, 30, 1, 30, 0, DateTimeKind.Utc);

var result = _parser.TryParseFuzzyTime("in 10 minutes", utcReference, "America/Chicago");

Assert.True(result.IsSuccess);
Assert.Equal(new DateTime(2025, 12, 30, 1, 40, 0, DateTimeKind.Utc), result.Value);
}

[Fact]
public void TryParseFuzzyTimeWithTimezoneKeepsLocalReferenceForNextWeek()
{
var utcReference = new DateTime(2025, 12, 30, 1, 30, 0, DateTimeKind.Utc);

var result = _parser.TryParseFuzzyTime("next week", utcReference, "America/Chicago");

Assert.True(result.IsSuccess);
Assert.Equal(new DateTime(2026, 1, 5, 19, 30, 0, DateTimeKind.Unspecified), result.Value);
}
}
Loading
Loading