Reconcile a week of local work with origin's iCloud CalDAV fix (PR #39)

.githooks/pre-commit

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Auto-resync the vendored gps2asp/ mirror before commit, so the CI
+# vendor-guard (.github/workflows/vendor-guard.yml) never has to catch
+# drift after the fact. Runs scripts/sync_vendored.py in write mode when
+# the commit touches src/gps2asp/, then stages the resynced output.
+#
+# Tracked at .githooks/pre-commit — enable once per clone with:
+#   git config core.hooksPath .githooks
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+if git diff --cached --name-only --diff-filter=ACMR | grep -q '^src/gps2asp/'; then
+    .venv/bin/python scripts/sync_vendored.py
+    git add -A -- custom_components/asp_parking/gps2asp/
+fi

README.md

@@ -36,7 +36,7 @@ It's a plain HTML/CSS/JS page — no build step, no install, no server-side code
 
 **Where the data comes from.** The demo does **not** call any live API from the browser.
 It reads a **dated snapshot** committed to the repo at
-[`docs/demo/data/demo.json`](docs/demo/data/demo.json) (snapshot date: **2026-07-28**),
+[`docs/demo/data/demo.json`](docs/demo/data/demo.json) (snapshot date: **2026-08-02**),
 plus the matched segment geometries in `docs/demo/data/demo-segments.geojson`. The snapshot
 stores *weekly recurring patterns* rather than absolute datetimes, and the page recomputes the
 next move time in your browser at NYC time — so the "next move" stays correct even though the
@@ -52,20 +52,21 @@ needs a token.
 
 This requires two things the demo page itself does not: the **spatial index** must be present
 locally, and the script needs **network access to the NYC Open Data (SODA) API**. The index is
-gitignored (~95 MB), so build it once with `python scripts/build_index.py` **or** download the
+gitignored (~95 MB), so build it once with `.venv/bin/python scripts/build_index.py` **or** download the
 released `index-v1` asset from the [Releases page](https://github.com/Pascal-ZeGerman/GPS2ASP-Resolver/releases).
 Setting a `NYC_OPEN_DATA_APP_TOKEN` environment variable is optional but helps avoid SODA rate
 limiting. The generated `demo.json`/`demo-segments.geojson` are the only files committed — the
 index never is.
 
-**Running it locally.** Serve the folder over HTTP (opening `index.html` via `file://` won't
-let the page `fetch()` its JSON):
+**Running it locally.** Serve the whole `docs/` tree over HTTP (opening `index.html` via `file://`
+won't let the page `fetch()` its JSON, and serving `docs/demo` alone 404s on the shared
+`../common.js`/`../common.css` the page loads):
 
 ```bash
-python -m http.server --directory docs/demo 8000
+.venv/bin/python -m http.server --directory docs 8000
 ```
 
-Then visit <http://localhost:8000/>.
+Then visit <http://localhost:8000/demo/>.
 
 **Hosting it.** The repo ships a [`.github/workflows/pages.yml`](.github/workflows/pages.yml)
 workflow that publishes the committed `docs/` tree to **GitHub Pages** on every push to `docs/`

custom_components/asp_parking/__init__.py

@@ -167,7 +167,7 @@ async def _async_download_index(hass: HomeAssistant) -> None:
             title="ASP Parking: Setup Error",
             notification_id="asp_parking_index_error",
         )
-        logger.error("ASP Parking: index download failed: %s", err)
+        logger.exception("ASP Parking: index download failed: %s", err)
         raise
 
 
@@ -240,7 +240,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     try:
         coordinator = ASPParkingCoordinator(hass, entry)
     except ImportError as err:
-        logger.error(
+        logger.exception(
             "ASP Parking: gps2asp vendored package is incomplete -- "
             "reinstall via HACS. (%s)",
             err,
@@ -265,7 +265,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     try:
         await coordinator.async_start()
     except Exception as err:  # noqa: BLE001 — defence-in-depth: catch all startup failures
-        logger.error(
+        logger.exception(
             "ASP Parking: coordinator.async_start() raised %s: %s; "
             "see HA logs for traceback",
             type(err).__name__,

custom_components/asp_parking/caldav_sync.py

@@ -184,7 +184,7 @@ async def __aexit__(self, *exc_info: Any) -> None:
             try:
                 loop = asyncio.get_running_loop()
                 await loop.run_in_executor(None, client.close)
-            except Exception:
+            except Exception:  # noqa: BLE001 — close() must never mask the original error
                 # Use DEBUG when we're already inside exception handling (e.g.
                 # CancelledError during HA shutdown) — close failures in that
                 # context are expected and not user-actionable.  Use WARNING

custom_components/asp_parking/coordinator.py

@@ -44,6 +44,7 @@
 
 from zoneinfo import ZoneInfo
 
+from .gps2asp.dataset_labels import BOROUGH_NAMES as _BOROUGH_NAMES
 from .gps2asp.resolver import convert, resolve
 from .gps2asp.resolver.exceptions import (
     AmbiguousResolutionError,
@@ -130,14 +131,6 @@
 
 _METRES_TO_FEET = 3.28084  # 1 metre = 3.28084 US survey feet
 
-_BOROUGH_NAMES: dict[str, str] = {
-    "1": "Manhattan",
-    "2": "Bronx",
-    "3": "Brooklyn",
-    "4": "Queens",
-    "5": "Staten Island",
-}
-
 
 class RebuildPath(Enum):
     """Phase 38 (IDX-05): which executor strategy services a rebuild request.

custom_components/asp_parking/gps2asp/dataset_common.py

@@ -0,0 +1,109 @@
+"""Shared constants for the offline dataset dumper scripts.
+
+``build_coverage_dataset.py`` and ``build_demo_dataset.py`` are both
+presentation-layer snapshot dumpers that reproject EPSG:2263 geometry to
+WGS84 and label CSCL borough codes. This module is the single source for
+that shared, non-resolver-logic plumbing so the two dumpers never drift.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable, Iterable
+from pathlib import Path
+from typing import TypeVar
+
+from pyproj import Transformer
+
+from .dataset_labels import (
+    BOROUGH_NAMES,
+    SIDE_LABELS,
+    borough_name,
+    cleaning_day_names,
+)
+from .resolver.spatial_index import SpatialIndex
+
+__all__ = [
+    "BOROUGH_NAMES",
+    "SIDE_LABELS",
+    "TO_WGS84",
+    "bounded_gather",
+    "borough_name",
+    "cleaning_day_names",
+    "load_segment_records_with_raw_count",
+]
+
+_T = TypeVar("_T")
+_R = TypeVar("_R")
+
+# Reverse of resolver/converter.py's forward transform: EPSG:2263 -> WGS84.
+# always_xy=True yields (lon, lat) — exactly GeoJSON coordinate order.
+TO_WGS84 = Transformer.from_crs("EPSG:2263", "EPSG:4326", always_xy=True)
+
+
+def _default_segments_path() -> Path:
+    """Default ``segments.json`` location, honoring ``GPS2ASP_INDEX_DIR``.
+
+    Reuses ``SpatialIndex.resolve_index_dir``'s own precedence (env var, then
+    the package-bundled default) so this dumper never reads a different
+    index than the live resolver path ``build_demo_dataset.py`` uses via
+    ``SpatialIndex.get()``.
+    """
+    return SpatialIndex.resolve_index_dir() / "segments.json"
+
+
+def _load_raw_segments(path: Path | None = None) -> dict:
+    return json.loads((path or _default_segments_path()).read_text())
+
+
+def load_segment_records_with_raw_count(
+    path: Path | None = None,
+) -> tuple[dict[str, dict], int]:
+    """Load ``segments.json`` into a filtered record map, plus the pre-filter
+    raw count, from a single parse of ``segments.json``.
+
+    Filters to dict records carrying ``geometry_wkt`` — the only records
+    either dumper can use (for a map midpoint/render or a schedule resolve).
+    Callers that need both the filtered records and the raw count (e.g. a
+    "never omit a segment" self-check) should use this rather than parsing
+    the (multi-MB) index file twice.
+    """
+    raw = _load_raw_segments(path)
+    filtered = {
+        str(seg_id): rec
+        for seg_id, rec in raw.items()
+        if isinstance(rec, dict) and "geometry_wkt" in rec
+    }
+    return filtered, len(raw)
+
+
+async def bounded_gather(
+    items: Iterable[_T],
+    worker: Callable[[_T], Awaitable[_R]],
+    concurrency: int,
+) -> list[_R]:
+    """Run ``worker`` over every item concurrently, bounded by ``concurrency``.
+
+    Both offline dataset dumpers need the same semaphore-bounded-gather
+    idiom (each item is an independent I/O-bound resolve: one point resolve
+    for the demo dumper, one SODA group fetch for the coverage dumper).
+    Factored here so a future fix to the bounded-concurrency pattern (e.g.
+    propagating the first exception, adding a timeout) doesn't have to be
+    hand-ported between the two dumper scripts.
+
+    Args:
+        items: The items to process; result order matches ``items`` order.
+        worker: Async callable applied to each item under the semaphore.
+        concurrency: Maximum number of ``worker`` calls in flight at once.
+
+    Returns:
+        Results in the same order as ``items``.
+    """
+    semaphore = asyncio.Semaphore(concurrency)
+
+    async def _bounded(item: _T) -> _R:
+        async with semaphore:
+            return await worker(item)
+
+    return await asyncio.gather(*(_bounded(item) for item in items))

custom_components/asp_parking/gps2asp/dataset_labels.py

@@ -0,0 +1,60 @@
+"""Presentation-label constants shared by the live HA integration and the
+offline dataset dumper scripts.
+
+Split out of ``dataset_common`` so importing these plain dicts (from
+``coordinator.py`` and ``sensor.py``) doesn't also pull in that module's
+pyproj/asyncio dumper plumbing, which HA never uses.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .schedule.models import TimeWindow
+
+# CSCL borough code -> human name. Single source of truth shared by
+# coordinator.py and both offline dataset dumpers so the three never drift.
+BOROUGH_NAMES: dict[str, str] = {
+    "1": "Manhattan",
+    "2": "Bronx",
+    "3": "Brooklyn",
+    "4": "Queens",
+    "5": "Staten Island",
+}
+
+
+def borough_name(borocode: str | None) -> str | None:
+    """Map a CSCL borough code to its human name, or None when unknown."""
+    if borocode is None:
+        return None
+    return BOROUGH_NAMES.get(str(borocode))
+
+
+# side_of_street letter -> display label. Single source of truth shared by
+# sensor.py and build_demo_dataset.py so the two never drift.
+SIDE_LABELS: dict[str, str] = {
+    "N": "North side",
+    "S": "South side",
+    "E": "East side",
+    "W": "West side",
+}
+
+
+def cleaning_day_names(
+    windows: "list[TimeWindow] | tuple[TimeWindow, ...]",
+) -> list[str]:
+    """Ordered-unique cleaning-day display names from a schedule's windows.
+
+    ``windows`` is expected pre-sorted by day then start_time (the
+    ``WeeklySchedule.windows`` contract), so deduplicating by first
+    appearance yields the same day order as sorting the unique day values.
+    Single source of truth shared by sensor.py, build_demo_dataset.py, and
+    the HA-independent test mirror so the three never drift.
+    """
+    seen: list[str] = []
+    for window in windows:
+        name = window.day.name.title()
+        if name not in seen:
+            seen.append(name)
+    return seen

custom_components/asp_parking/gps2asp/resolver/spatial_index.py

@@ -50,15 +50,23 @@ class SpatialIndex:
     def __init__(self, index_dir: str | None = None) -> None:
         self._index = None
         self._segments = None
+        self._index_dir = self.resolve_index_dir(index_dir)
 
+    @staticmethod
+    def resolve_index_dir(index_dir: str | None = None) -> Path:
+        """Resolve the index directory using the constructor/env/default precedence.
+
+        Shared with ``dataset_common._default_segments_path`` so the offline
+        dataset dumpers always resolve ``segments.json`` from the same
+        directory the live resolver reads its index from.
+        """
         if index_dir is not None:
-            self._index_dir = Path(index_dir)
-        elif env_dir := os.environ.get("GPS2ASP_INDEX_DIR"):
-            self._index_dir = Path(env_dir)
-        else:
-            # Default: data/index/ relative to the gps2asp package
-            package_dir = Path(__file__).parent.parent
-            self._index_dir = package_dir / "data" / "index"
+            return Path(index_dir)
+        if env_dir := os.environ.get("GPS2ASP_INDEX_DIR"):
+            return Path(env_dir)
+        # Default: data/index/ relative to the gps2asp package
+        package_dir = Path(__file__).parent.parent
+        return package_dir / "data" / "index"
 
     @classmethod
     async def get(cls, index_dir: str | None = None) -> SpatialIndex:
@@ -312,3 +320,26 @@ def query_radius(
         results.sort(key=lambda c: c.distance_ft)
 
         return results
+
+    def get_segment_geometry_wkt(self, segment_id: object) -> str | None:
+        """Return the raw ``geometry_wkt`` for one segment id, or ``None``.
+
+        Reuses the already-loaded ``_segments`` metadata (the same dict
+        ``nearest()``/``query_radius()`` read) instead of re-parsing
+        segments.json. Callers that already resolved a point through this
+        singleton (e.g. dataset dumpers deriving a matched segment's display
+        geometry) get the lookup for free rather than paying a second,
+        independent full parse of the multi-megabyte index file.
+
+        Args:
+            segment_id: A segment id as returned on ``SegmentCandidate.segment_id``
+                (int or str; looked up via ``str(segment_id)``, matching the
+                string keys segments.json is loaded into).
+
+        Returns:
+            The segment's ``geometry_wkt``, or ``None`` if unloaded or not found.
+        """
+        if self._segments is None:
+            return None
+        seg_data = self._segments.get(str(segment_id))
+        return seg_data.get("geometry_wkt") if seg_data else None

custom_components/asp_parking/gps2asp/schedule/__init__.py

@@ -151,6 +151,7 @@ def compute_schedule(
         return ASPActiveNow(
             status="asp_active_now",
             active_window=active,
+            weekly_schedule=merged_schedule,
             on_street=on_street,
             from_street=from_street,
             to_street=to_street,

custom_components/asp_parking/gps2asp/schedule/models.py

@@ -173,6 +173,10 @@ class ASPActiveNow:
     Attributes:
         status: Discriminator literal "asp_active_now".
         active_window: The currently active cleaning window.
+        weekly_schedule: Full merged weekly schedule (all cleaning days/windows),
+            mirroring ScheduleFound.weekly_schedule. Preserves every cleaning day
+            even while one window is in progress, so downstream consumers (demo /
+            coverage dumpers, calendars) can render the complete pattern.
         on_street: Street name in CSCL format.
         from_street: Cross street at one end.
         to_street: Cross street at the other end.
@@ -191,6 +195,7 @@ class ASPActiveNow:
 
     status: Literal["asp_active_now"]
     active_window: CleaningWindow
+    weekly_schedule: WeeklySchedule
     on_street: str
     from_street: str
     to_street: str

custom_components/asp_parking/gps2asp/signs/__init__.py

@@ -42,6 +42,7 @@
 __all__ = [
     "retrieve_signs",
     "materialize_cached_records",
+    "normalize_street",
     "SignRetrievalResult",
     "SignRetrievalSuccess",
     "NoASPSigns",
@@ -130,7 +131,7 @@ def materialize_cached_records(
     )
 
 
-def _normalize_street(name: str) -> str:
+def normalize_street(name: str) -> str:
     """Normalize a street name for comparison (uppercase, strip, expand)."""
     return normalize_to_soda(name.upper().strip())
 
@@ -165,8 +166,8 @@ def _cross_streets_match(
         return False
 
     # Normalize the raw SODA record fields (uppercase, strip, expand abbreviations)
-    record_from = _normalize_street(record_from_raw)
-    record_to = _normalize_street(record_to_raw)
+    record_from = normalize_street(record_from_raw)
+    record_to = normalize_street(record_to_raw)
 
     # Generate all known variants of the CSCL cross-street names for matching
     # (name_variants expands abbreviations like AVE→AVENUE, PL→PLACE, etc.)