from __future__ import annotations

import re
from pathlib import Path


def slugify_company_name(company_name: str) -> str:
    """Convert a company name into a filesystem-safe identifier."""
    normalized = re.sub(r"[^a-zA-Z0-9]+", "-", company_name.strip().lower())
    return normalized.strip("-") or "unknown-company"


def save_debug_html(company_name: str, html: str, stage: str, debug_dir: Path) -> Path | None:
    """Persist raw HTML so scraper failures can be inspected outside the app."""
    if not html:
        return None

    debug_dir.mkdir(parents=True, exist_ok=True)
    file_name = f"{slugify_company_name(company_name)}__{stage}.html"
    output_path = debug_dir / file_name
    output_path.write_text(html, encoding="utf-8")
    return output_path


def log_debug_header(company_name: str) -> None:
    print("=" * 60)
    print(f"COMPANY: {company_name}")


def log_debug_line(label: str, value: object) -> None:
    print(f"{label}: {value}")