from recoil.pipeline._lib.taxonomy import slugify_asset_id


def subject_id_norm(subject: str) -> str:
    """THE subject normalizer shared by resolver readers and gates."""
    return slugify_asset_id(subject)


def subject_stem(subject: str) -> str:
    """Canonical HYPHEN stem fragment for a subject id inside a ref filename."""
    return subject_id_norm(subject).replace("_", "-")


def ref_filename(subject: str, kind: str, ext: str = "png", view: str | None = None) -> str:
    """Canonical shelf-hero filename. Default '{subject-stem}-{kind}.{ext}';
    with a view qualifier '{subject-stem}-{kind}-{view}.{ext}' (turn views)."""
    e = ext.lstrip(".")
    if view:
        return f"{subject_stem(subject)}-{kind}-{view}.{e}"
    return f"{subject_stem(subject)}-{kind}.{e}"