from typing import List, Tuple
import yaml

REQUIRED_TOP_KEYS = [
    "STATE",
    "CARD_TYPE",
    "CARD_ID",
    "VERSION",
    "TIMESTAMP",
    "TITLE",
    "DESCRIPTION",
]

def validate_card_yaml(card_yaml: str) -> Tuple[bool, List[str]]:
    errors: List[str] = []
    if not card_yaml or not card_yaml.strip():
        return False, ["Empty YAML"]

    try:
        doc = yaml.safe_load(card_yaml)
    except Exception as e:
        return False, [f"YAML parse failed: {e}"]

    if not isinstance(doc, dict):
        return False, ["YAML root is not a mapping/dict"]

    for k in REQUIRED_TOP_KEYS:
        if k not in doc:
            errors.append(f"Missing required key: {k}")

    # LOCK should be present in STATE (format handled by generator)
    if "LOCK" not in doc:
        # Not fatal, but expected
        errors.append("Missing key: LOCK (expected)")

    return (len(errors) == 0), errors