"""Shared constants and helpers for the Shoreliser algorithms.

The reference epoch used to convert dates <-> integer day indices was previously
hardcoded inconsistently across steps (1984-01-01 in steps 2/3, 1984-06-01 in
step 4). It is now a single shared default, exposed as an editable parameter on
each algorithm so the whole pipeline stays consistent.
"""

from datetime import datetime

# Single source of truth for the day-index epoch (days == 0 on this date).
DEFAULT_REF_DATE = '1984-01-01'

# Field-name contract flowing between pipeline steps.
F_DATE_CLEAN = 'date_clean'   # normalized YYYYMMDD string (step 1 output)
F_LONGI = 'longi'             # along-shore transect index
F_DAYS = 'days'              # integer day offset from the reference epoch
F_DIST = 'dist_m'            # beach width / transect distance in metres
F_LONGI_INT = 'LONGI_INT'    # along-shore index on the baseline


def parse_ref_date(text, default=DEFAULT_REF_DATE):
    """Parse a 'YYYY-MM-DD' reference date string into a datetime.

    Falls back to the module default if *text* is empty.
    """
    text = (text or '').strip() or default
    try:
        return datetime.strptime(text, '%Y-%m-%d')
    except ValueError:
        raise ValueError(
            "Reference date must be in YYYY-MM-DD format (e.g. 1984-01-01)."
        )
