"""Helpers for asserting frontend wiring from the backend test suite.

Most of this suite checks frontend behaviour by reading TSX files and
asserting that literal substrings occur in them. That reds the suite on every
rename and every copy change while proving nothing about behaviour: renaming a
button label is not a regression, and ``source.count("useEffect(") == 1`` is a
formatting rule, not a contract.

These helpers keep the useful half of that idea — that a documented product
contract must remain wired somewhere in the frontend — and drop the brittle
half. Assert on identifiers, API paths and prop names, which only change when
the wiring genuinely changes. Do not assert on user-visible copy; put that in
a frontend component test where the rendered output can be checked properly.
"""

from __future__ import annotations

import re
from pathlib import Path

ROOT = Path(__file__).resolve().parents[2]
FRONTEND_SRC = ROOT / "frontend" / "src"


def read_frontend(relative_path: str) -> str:
    """Read one frontend source file relative to ``frontend/src``."""

    return (FRONTEND_SRC / relative_path).read_text(encoding="utf-8")


def assert_wired(source: str, *identifiers: str, context: str = "frontend source") -> None:
    """Every identifier must appear in ``source``.

    Use for symbols, hook names, prop names and API paths — things a refactor
    renames deliberately — never for sentences shown to a user.
    """

    missing = [identifier for identifier in identifiers if identifier not in source]
    assert not missing, f"{context} no longer wires: {missing}"


def assert_calls(source: str, function_name: str, *, first_argument: str) -> None:
    """Assert ``function_name`` is called with ``first_argument`` as argument 1.

    Tolerates whatever the remaining arguments have been refactored into, which
    is the part that keeps changing while the wiring stays the same.
    """

    pattern = rf"{re.escape(function_name)}\(\s*{re.escape(first_argument)}\s*[,)]"
    assert re.search(pattern, source), f"{function_name}({first_argument}, …) is no longer called"


def assert_mentions(source: str, *phrases: str, context: str = "frontend source") -> None:
    """Case-insensitive check that a concept is still surfaced to the operator.

    A deliberately weak assertion: it survives rewording but still fails if a
    whole explanation is deleted. Prefer ``assert_wired`` where an identifier
    exists to check instead.
    """

    folded = source.casefold()
    missing = [phrase for phrase in phrases if phrase.casefold() not in folded]
    assert not missing, f"{context} no longer mentions: {missing}"