fix: chronological sort of periods in sections_db (Q12027 before Q32026)

storage/sections_db.py

@@ -77,8 +77,31 @@ def get_section(ticker: str, period: str, section: str) -> Optional[str]:
     return row[0] if row else None
 
 
+def _period_sort_key(period: str) -> tuple[int, int]:
+    """Parse 'Q12027' → (2027, 1) for correct chronological sort (newest first).
+
+    Falls back to (0, 0) for unparseable strings (e.g. 'FY2024').
+    """
+    if not period:
+        return (0, 0)
+    if period.startswith("Q") and len(period) >= 6:
+        try:
+            body = period[1:]          # "12027"
+            year = int(body[-4:])      # 2027
+            quarter = int(body[:-4])   # 1
+            return (year, quarter)
+        except (ValueError, IndexError):
+            pass
+    if period.startswith("FY") and len(period) == 6:
+        try:
+            return (int(period[2:]), 0)
+        except ValueError:
+            pass
+    return (0, 0)
+
+
 def get_periods_for_ticker(ticker: str, form_type: Optional[str] = None) -> list[str]:
-    """Return all period strings stored for a ticker, sorted newest first.
+    """Return all period strings stored for a ticker, sorted newest first (chronologically).
 
     Optionally filtered by form_type (e.g. '10-Q').
     """
@@ -87,20 +110,14 @@ def get_periods_for_ticker(ticker: str, form_type: Optional[str] = None) -> list
     with sqlite3.connect(SECTIONS_DB_PATH) as conn:
         if form_type:
             rows = conn.execute(
-                """
-                SELECT DISTINCT period FROM sections
-                WHERE ticker=? AND form_type=?
-                ORDER BY period DESC
-                """,
+                "SELECT DISTINCT period FROM sections WHERE ticker=? AND form_type=?",
                 (ticker.upper(), form_type),
             ).fetchall()
         else:
             rows = conn.execute(
-                """
-                SELECT DISTINCT period FROM sections
-                WHERE ticker=?
-                ORDER BY period DESC
-                """,
+                "SELECT DISTINCT period FROM sections WHERE ticker=?",
                 (ticker.upper(),),
             ).fetchall()
-    return [r[0] for r in rows]
+    periods = [r[0] for r in rows]
+    periods.sort(key=_period_sort_key, reverse=True)
+    return periods

tests/test_sections_db.py

@@ -61,6 +61,19 @@ def test_get_periods_returns_empty_when_no_db(tmp_path):
         assert get_periods_for_ticker("AAPL") == []
 
 
+def test_get_periods_chronological_sort(tmp_path):
+    """Q12027 must come before Q32026 — chronological not alphabetical."""
+    db_path = _tmp_db(tmp_path)
+    with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):
+        from storage.sections_db import init_sections_db, upsert_section, get_periods_for_ticker
+        init_sections_db()
+        for period in ["Q32026", "Q22026", "Q12027", "Q12026"]:
+            upsert_section("NVDA", period, "10-Q", "mda", f"text {period}")
+        periods = get_periods_for_ticker("NVDA", form_type="10-Q")
+        assert periods[0] == "Q12027", f"Expected Q12027 first, got {periods}"
+        assert periods[1] == "Q32026", f"Expected Q32026 second, got {periods}"
+
+
 def test_ticker_is_case_insensitive(tmp_path):
     db_path = _tmp_db(tmp_path)
     with patch("storage.sections_db.SECTIONS_DB_PATH", db_path):