fix(spreadsheet): reject duplicate headers in get_all_values path

Fail fast with GSpreadException when worksheet header row contains
duplicates, use zip(strict=True) after row padding, and add regression
tests for the helper and read_spreadsheet integration.

Author: northdpole

application/tests/spreadsheet_test.py

@@ -4,10 +4,13 @@
 from pprint import pprint
 from unittest import mock
 
+import gspread
+
 from application import create_app, sqla  # type: ignore
 from application.database import db
 from application.defs import cre_defs as defs
 from application.utils.spreadsheet import *
+from application.utils.spreadsheet import _records_from_worksheet_values
 from application.tests.utils.data_gen import export_format_data
 
 
@@ -216,3 +219,40 @@ def test_read_spreadsheet_short_row_padded(
         )
 
         self.assertEqual(result["Short Row"], [{"Col A": "only-a", "Col B": ""}])
+
+    def test_records_from_worksheet_values_duplicate_headers(self) -> None:
+        with self.assertRaises(gspread.exceptions.GSpreadException) as ctx:
+            _records_from_worksheet_values(
+                [["Col A", "Col B", "Col A"], ["x", "y", "z"]]
+            )
+        self.assertIn("Duplicate worksheet headers", str(ctx.exception))
+        self.assertIn("Col A", str(ctx.exception))
+
+    @mock.patch("application.utils.spreadsheet.gspread.service_account")
+    @mock.patch("application.utils.spreadsheet.gspread.oauth")
+    def test_read_spreadsheet_duplicate_headers(
+        self, mock_oauth, mock_service_account
+    ) -> None:
+        fake_ws = mock.MagicMock()
+        fake_ws.title = "Dup Headers"
+        fake_ws.get_all_values.return_value = [
+            ["Name", "Name"],
+            ["row"],
+        ]
+
+        fake_sh = mock.MagicMock()
+        fake_sh.worksheets.return_value = [fake_ws]
+
+        fake_client = mock.MagicMock()
+        fake_client.open_by_url.return_value = fake_sh
+        mock_oauth.return_value = fake_client
+        mock_service_account.return_value = fake_client
+
+        result = read_spreadsheet(
+            "https://example.com/fake-spreadsheet-url",
+            "Test Spreadsheet",
+            validate=False,
+            parse_numbered_only=False,
+        )
+
+        self.assertEqual(result, {})

application/utils/spreadsheet.py

@@ -27,14 +27,24 @@ def findDups(x):
 
 
 def _records_from_worksheet_values(rows: List[List[Any]]) -> List[Dict[str, Any]]:
-    """Build row dicts from raw gspread values without numeric coercion."""
+    """Build row dicts from raw worksheet cell values without numeric coercion.
+
+    Uses the first row as column headers. Short data rows are padded with empty
+    strings. Raises ``GSpreadException`` when duplicate header names are present
+    so callers fail fast instead of silently collapsing columns in ``dict(zip)``.
+    """
     if not rows:
         return []
     headers = rows[0]
+    duplicates = sorted(findDups(headers))
+    if duplicates:
+        raise gspread.exceptions.GSpreadException(
+            f"Duplicate worksheet headers: {duplicates}"
+        )
     records: List[Dict[str, Any]] = []
     for row in rows[1:]:
         padded = list(row) + [""] * max(0, len(headers) - len(row))
-        records.append(dict(zip(headers, padded[: len(headers)])))
+        records.append(dict(zip(headers, padded[: len(headers)], strict=True)))
     return records