Normalize Cycle interface for consistency across libraries

- Rename `current` to `effective` and `isCurrent` to `isEffective`
- Make `yymm` internal and remove redundant `fullYear`
- Make `previous`/`next` return optional for API consistency
- Add `dateRange` property returning DateInterval
- Add `contains(_:)` method to check if date falls within cycle
- Add `cycle(for:)` static factory method
- Change `expirationDate` to return exact expiration moment
- Move factory methods to separate extension for SwiftLint compliance
- Add comprehensive Cycle tests

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: RISCfuture

Sources/SwiftCIFP/CIFP.swift

@@ -558,7 +558,7 @@ private struct CIFPBuilder {
       guard let c = Cycle(yymm: cycleStr) else { continue }
       return c
     }
-    return Cycle.current
+    return Cycle.effective
   }
 
   private func buildAirways(errorCallback: ((Error, Int?) -> Void)?) -> [String: Airway] {

Sources/SwiftCIFP/CIFPData.swift

@@ -160,7 +160,7 @@ public actor CIFPData {
       dataSupplier: "TEST",
       descriptiveText: []
     )
-    self.cycle = .current
+    self.cycle = .effective
     self.gridMORAs = []
     self.vhfNavaids = vhfNavaids
     self.ndbNavaids = ndbNavaids

Sources/SwiftCIFP/Cycle.swift

@@ -50,8 +50,8 @@ extension Cycle {
   /// AIRAC cycle length in days.
   private static let cycleLengthDays = 28
 
-  /// The current AIRAC cycle.
-  public static var current: Self {
+  /// The currently effective AIRAC cycle.
+  public static var effective: Self {
     let calendar = Calendar(identifier: .gregorian)
     let now = Date()
 
@@ -81,51 +81,65 @@ extension Cycle {
     )
   }
 
-  /// The expiration date of this cycle (day before next cycle).
+  /// The expiration date of this cycle (midnight UTC when cycle expires).
+  ///
+  /// This is the exact moment the cycle expires, which is also the effective date of the next cycle.
   public var expirationDate: Date? {
     guard let effectiveDate else { return nil }
     let calendar = Calendar(identifier: .gregorian)
-    return calendar.date(byAdding: .day, value: Self.cycleLengthDays - 1, to: effectiveDate)
+    return calendar.date(byAdding: .day, value: Self.cycleLengthDays, to: effectiveDate)
+  }
+
+  /// The date range when this cycle is effective.
+  ///
+  /// The range starts at `effectiveDate` and ends at `expirationDate` (exclusive).
+  public var dateRange: DateInterval? {
+    guard let effectiveDate, let expirationDate else { return nil }
+    return DateInterval(start: effectiveDate, end: expirationDate)
+  }
+
+  /// Returns whether the given date falls within this cycle's effective period.
+  ///
+  /// - Parameter date: The date to check.
+  /// - Returns: `true` if the date falls within this cycle's effective period.
+  public func contains(_ date: Date) -> Bool {
+    guard let dateRange else { return false }
+    return dateRange.contains(date)
   }
 }
 
 // MARK: - Cycle Navigation
 
 extension Cycle {
   /// The previous cycle.
-  public var previous: Self {
+  public var previous: Self? {
     if cycleNumber > 1 {
       return Self(year: year, cycleNumber: cycleNumber - 1)
     }
     return Self(year: year - 1, cycleNumber: 13)
   }
 
   /// The next cycle.
-  public var next: Self {
+  public var next: Self? {
     if cycleNumber < 13 {
       return Self(year: year, cycleNumber: cycleNumber + 1)
     }
     return Self(year: year + 1, cycleNumber: 1)
   }
 
   /// Whether this cycle is currently effective.
-  public var isCurrent: Bool {
-    self == Self.current
+  public var isEffective: Bool {
+    self == Self.effective
   }
 }
 
 // MARK: - String Representation
 
 extension Cycle {
-  /// The YYMM string representation.
-  public var yymm: String {
+  /// The YYMM string representation (used internally for identification).
+  var yymm: String {
     String(format: "%02d%02d", year % 100, cycleNumber)
   }
-
-  /// The full 4-digit year.
-  public var fullYear: Int {
-    Int(year)
-  }
 }
 
 // MARK: - Comparable
@@ -152,3 +166,25 @@ extension Cycle: CustomStringConvertible {
     "AIRAC \(yymm)"
   }
 }
+
+// MARK: - Factory Methods
+
+extension Cycle {
+  /// Returns the cycle that contains the given date.
+  ///
+  /// - Parameter date: The date to find the cycle for.
+  /// - Returns: The cycle containing the date, or `nil` if the cycle cannot be determined.
+  public static func cycle(for date: Date) -> Self? {
+    let calendar = Calendar(identifier: .gregorian)
+    let daysSinceRef = calendar.dateComponents([.day], from: referenceDate, to: date).day ?? 0
+
+    // Handle dates before the reference
+    guard daysSinceRef >= 0 else { return nil }
+
+    let totalCycles = daysSinceRef / cycleLengthDays
+    let year = 2024 + (totalCycles / 13)
+    let cycleInYear = (totalCycles % 13) + 1
+
+    return Self(year: UInt(year), cycleNumber: UInt8(cycleInYear))
+  }
+}

Sources/SwiftCIFP/Documentation.docc/GettingStarted.md

@@ -134,11 +134,11 @@ print("Data cycle: \(cifp.cycle)")
 print("Effective: \(cifp.cycle.effectiveDate)")
 print("Expires: \(cifp.cycle.expirationDate)")
 
-// Get current AIRAC cycle
-let current = Cycle.current
-print("Current cycle: \(current.yymm)")
+// Get effective AIRAC cycle
+let effective = Cycle.effective
+print("Effective cycle: \(effective)")
 
 // Navigate between cycles
-let next = current.next
-let previous = current.previous
+let next = effective.next
+let previous = effective.previous
 ```

Sources/SwiftCIFP_E2E/SwiftCIFP_E2E.swift

@@ -40,7 +40,7 @@ struct SwiftCIFP_E2E: AsyncParsableCommand {
   /// URL to download the current CIFP cycle from the FAA.
   private var currentCycleURL: URL {
     get throws {
-      let cycle = Cycle.current
+      let cycle = Cycle.effective
       guard let effectiveDate = cycle.effectiveDate else {
         throw ValidationError("Failed to calculate current cycle effective date")
       }

Tests/SwiftCIFPTests/SwiftCIFPTests.swift

@@ -291,21 +291,117 @@ struct CycleTests {
     #expect(cycle?.effectiveDate != nil)
   }
 
-  @Test("Cycle yymm format")
-  func yymmFormat() {
-    let cycle = Cycle(yymm: "2506")
-    #expect(cycle?.yymm == "2506")
+  @Test("Cycle navigation with optional returns")
+  func navigation() {
+    let cycle = Cycle(yymm: "2501")
+    #expect(cycle != nil)
+    if let cycle {
+      #expect(cycle.next?.cycleNumber == 2)
+      #expect(cycle.next?.year == 2025)
+      #expect(cycle.previous?.cycleNumber == 13)
+      #expect(cycle.previous?.year == 2024)
+    }
   }
 
-  @Test("Cycle navigation")
-  func navigation() {
+  @Test("Cycle effective returns currently effective cycle")
+  func effectiveCycle() {
+    let effective = Cycle.effective
+    #expect(effective.isEffective)
+    #expect(effective.cycleNumber >= 1 && effective.cycleNumber <= 13)
+  }
+
+  @Test("Cycle cycle(for:) returns correct cycle")
+  func cycleForDate() {
+    // Use the reference date (Jan 25, 2024 is cycle 2401)
+    var calendar = Calendar(identifier: .gregorian)
+    calendar.timeZone = .gmt
+    let refDate = calendar.date(
+      from: DateComponents(timeZone: .gmt, year: 2024, month: 1, day: 25)
+    )!
+
+    let cycle = Cycle.cycle(for: refDate)
+    #expect(cycle != nil)
+    #expect(cycle?.year == 2024)
+    #expect(cycle?.cycleNumber == 1)
+  }
+
+  @Test("Cycle dateRange covers full cycle")
+  func dateRange() {
+    let cycle = Cycle(yymm: "2501")
+    #expect(cycle != nil)
+    if let cycle {
+      let dateRange = cycle.dateRange
+      #expect(dateRange != nil)
+
+      // Duration should be 28 days
+      let expectedDuration: TimeInterval = 28 * 24 * 60 * 60
+      #expect(dateRange?.duration == expectedDuration)
+    }
+  }
+
+  @Test("Cycle contains returns true for date within cycle")
+  func containsDateWithinCycle() {
+    let cycle = Cycle(yymm: "2501")
+    #expect(cycle != nil)
+    if let cycle, let effectiveDate = cycle.effectiveDate {
+      // A date 14 days into the cycle should be contained
+      var calendar = Calendar(identifier: .gregorian)
+      calendar.timeZone = .gmt
+      let midCycleDate = calendar.date(byAdding: .day, value: 14, to: effectiveDate)!
+      #expect(cycle.contains(midCycleDate))
+    }
+  }
+
+  @Test("Cycle contains returns false for date outside cycle")
+  func containsDateOutsideCycle() {
+    let cycle = Cycle(yymm: "2501")
+    #expect(cycle != nil)
+    if let cycle, let effectiveDate = cycle.effectiveDate {
+      // A date 30 days after the effective date should not be contained
+      var calendar = Calendar(identifier: .gregorian)
+      calendar.timeZone = .gmt
+      let afterDate = calendar.date(byAdding: .day, value: 30, to: effectiveDate)!
+      #expect(!cycle.contains(afterDate))
+    }
+  }
+
+  @Test("Cycle expirationDate returns exact moment")
+  func expirationDateExactMoment() {
     let cycle = Cycle(yymm: "2501")
     #expect(cycle != nil)
     if let cycle {
-      #expect(cycle.next.cycleNumber == 2)
-      #expect(cycle.next.year == 2025)
+      let expirationDate = cycle.expirationDate
+      #expect(expirationDate != nil)
+
+      // expirationDate should equal next cycle's effectiveDate
+      #expect(expirationDate == cycle.next?.effectiveDate)
     }
   }
+
+  @Test("Cycle comparison")
+  func comparison() {
+    let older = Cycle(yymm: "2501")
+    let newer = Cycle(yymm: "2502")
+    let same = Cycle(yymm: "2501")
+    #expect(older != nil && newer != nil && same != nil)
+    if let older, let newer, let same {
+      #expect(older < newer)
+      #expect(newer > older)
+      #expect(older == same)
+    }
+  }
+
+  @Test("Cycle isEffective returns true for effective cycle")
+  func isEffective() {
+    let effective = Cycle.effective
+    #expect(effective.isEffective)
+
+    // A past cycle should not be effective
+    let past = Cycle(yymm: "2401")
+    #expect(past != nil)
+    // Past cycle may or may not be effective depending on when test runs
+    _ = past?.isEffective
+  }
 }
 
 // MARK: - PathTerminator Tests