brain-of-reese/tests/unit/test_theming.py

"""Unit: the built-in identity palette + the effective-settings resolver
(phase 91, task 01).

Covers ``app/core/theming.py`` — the single source of the built-in
identity palette (re-homed from the retired phase-62 CSS-file themes'
authoring guide before task 03 deleted it) and the DB-over-env /
DB-over-built-in resolver shared by ``/api/ui-settings`` and
``/api/config``:

* ``BUILTIN_COLORS`` — the DRIFT GUARD: the 9 built-ins must equal the
  values parsed straight out of ``frontend/assets/styles.css``'s
  ``:root`` block, so the Python palette and the stylesheet can never
  silently diverge;
* ``theme_style_tag`` — the byte-identical contract (all built-in →
  ``""``) and the exact tag shape (all 9 variables, ``COLOR_FIELDS``
  order, lowercased hex);
* ``effective_settings`` — missing row → env strings + built-ins; a DB
  row's set columns win; an empty-string DB string falls back to env
  (the resolver treats "" as unset, B1). House DB-test pattern (the
  ``test_tokens`` precedent): the real compose Postgres, skipped with
  clear instructions when the stack is not up.
"""
from __future__ import annotations

import base64
import hashlib
import re
from pathlib import Path
from typing import Any

from sqlalchemy import select
from sqlalchemy.orm import Session

from app.config import Settings
from app.core import theming
from app.models import UiSettings

REPO_ROOT = Path(__file__).resolve().parents[2]
STYLES_CSS = REPO_ROOT / "frontend" / "assets" / "styles.css"


def _delete_row() -> Any:
    from sqlalchemy import delete

    return delete(UiSettings).where(UiSettings.id == 1)


def _start_row_missing(db: Session) -> None:
    """The single row is global state: wipe it so every DB test starts
    from the row-missing state it asserts (a stale row from an earlier
    interrupted run must not break them)."""
    db.execute(_delete_row())
    db.commit()


def _root_declarations() -> dict[str, str]:
    """The ``--name: value`` declarations of styles.css's (first)
    ``:root`` block, comments stripped, in file order."""
    css = STYLES_CSS.read_text(encoding="utf-8")
    match = re.search(r":root\s*\{", css)
    assert match is not None, "styles.css must have a :root block"
    block = css[match.end() : css.index("}", match.end())]
    block = re.sub(r"/\*.*?\*/", "", block, flags=re.S)
    return dict(re.findall(r"(--[a-z-]+)\s*:\s*([^;]+);", block))


def test_builtin_colors_match_styles_css_root() -> None:
    """The drift guard: every built-in equals the stylesheet's ``:root``
    value for the same variable (and ``BUILTIN_COLORS`` names exactly
    the 9 identity variables — no more, no fewer)."""
    decls = _root_declarations()
    builtin_names = set(theming.BUILTIN_COLORS)
    assert builtin_names == {
        "bg", "surface", "ink", "ink_soft", "line", "grid_line",
        "brand", "brand_soft", "brand_ink",
    }, f"BUILTIN_COLORS must name exactly the 9 identity variables, got {sorted(builtin_names)}"
    for name, value in theming.BUILTIN_COLORS.items():
        css_name = f"--{name.replace('_', '-')}"
        assert css_name in decls, f"styles.css :root is missing {css_name}"
        assert decls[css_name].strip() == value, (
            f"{css_name} drifted: BUILTIN_COLORS has {value!r}, "
            f"styles.css has {decls[css_name].strip()!r}"
        )


def test_color_fields_are_the_nine_keys_in_readme_order() -> None:
    """``COLOR_FIELDS`` is the 9 keys in the themes-README order — the
    order the resolver, the API, and the tag renderer all rely on.
    (Phase 92, task 01: ``grid_line`` is the 9th identity variable,
    slotting in between ``line`` and ``brand`` — structural colors
    first, brand last.)"""
    assert theming.COLOR_FIELDS == (
        "bg", "surface", "ink", "ink_soft",
        "line", "grid_line", "brand", "brand_soft", "brand_ink",
    )
    assert theming.STRING_FIELDS == ("app_name", "input_placeholder", "footer_text")


def _env_settings() -> Settings:
    """An explicit env source (the resolver's optional ``settings``
    parameter) — deterministic values, independent of the local ``.env``
    (the ``/api/config`` env pins in test_api.py own the env-file
    behaviour; this unit module only needs stable fallbacks)."""
    return Settings(
        app_name="Env Name",
        input_placeholder="Env placeholder…",
        footer_text="Env footer",
    )


# ---------- effective_settings (real Postgres — house DB-test pattern) ----------


def test_effective_missing_row_is_env_strings_plus_builtins(db: Session) -> None:
    """A missing row (GET creates nothing) means "defaults": the env
    strings + the built-in palette, all 12 keys."""
    _start_row_missing(db)
    row = db.execute(select(UiSettings).where(UiSettings.id == 1)).scalars().first()
    assert row is None, "the test starts from a row-missing state"
    effective = theming.effective_settings(db, _env_settings())
    assert set(effective) == set(theming.STRING_FIELDS) | set(theming.COLOR_FIELDS)
    assert effective["app_name"] == "Env Name"
    assert effective["input_placeholder"] == "Env placeholder…"
    assert effective["footer_text"] == "Env footer"
    assert {k: effective[k] for k in theming.COLOR_FIELDS} == theming.BUILTIN_COLORS


def test_effective_db_row_wins_column_by_column(db: Session) -> None:
    """Set columns win, unset columns fall back — per column, so a
    partial row (only ``bg`` set) mixes the DB color with the built-ins
    and the env strings."""
    _start_row_missing(db)
    db.add(UiSettings(id=1, bg="#111111", app_name="DB Name"))
    db.commit()
    try:
        effective = theming.effective_settings(db, _env_settings())
        assert effective["bg"] == "#111111"  # DB wins
        assert effective["app_name"] == "DB Name"  # DB wins
        # Unset columns: env strings + the built-in colors.
        assert effective["input_placeholder"] == "Env placeholder…"
        assert effective["footer_text"] == "Env footer"
        for key in theming.COLOR_FIELDS:
            if key != "bg":
                assert effective[key] == theming.BUILTIN_COLORS[key]
    finally:
        db.execute(_delete_row())
        db.commit()


def test_effective_empty_string_db_string_falls_back_to_env(db: Session) -> None:
    """B1: an EMPTY string in the DB is unset — the resolver falls back
    to the env value (a hand-edited row with '' can't blank the UI).
    Colors: ``None`` → the built-in (an empty color is impossible through
    the API — the hex validator — the resolver's not-None rule covers
    the hand-edited edge by returning whatever the row holds)."""
    _start_row_missing(db)
    db.add(UiSettings(id=1, app_name=""))
    db.commit()
    try:
        effective = theming.effective_settings(db, _env_settings())
        assert effective["app_name"] == "Env Name"  # "" → env fallback
        assert effective["footer_text"] == "Env footer"
        assert effective["brand"] == theming.BUILTIN_COLORS["brand"]  # None → built-in
    finally:
        db.execute(_delete_row())
        db.commit()


def test_effective_without_explicit_settings_uses_get_settings(db: Session) -> None:
    """``settings=None`` (the design's call shape) resolves the env
    fallback from the cached :func:`app.config.get_settings` — the
    values it reports must be real ``str``s for all 12 keys."""
    from app.config import get_settings

    _start_row_missing(db)
    effective = theming.effective_settings(db)
    assert set(effective) == set(theming.STRING_FIELDS) | set(theming.COLOR_FIELDS)
    assert effective["app_name"] == get_settings().app_name
    for field in theming.STRING_FIELDS:
        assert isinstance(effective[field], str) and effective[field]
    assert all(re.fullmatch(r"#[0-9a-f]{6}", effective[k]) for k in theming.COLOR_FIELDS)
    assert {k: effective[k] for k in theming.COLOR_FIELDS} == theming.BUILTIN_COLORS


# ---------- theme_style_tag (pure) ----------


def test_theme_style_tag_all_builtins_is_empty_string() -> None:
    """The byte-identical contract: an unset (or "defaults saved")
    deployment serves NO tag — exactly the pre-phase-91 HTML."""
    assert theming.theme_style_tag(dict(theming.BUILTIN_COLORS)) == ""
    # The tag is PURE string-equality: uppercase hex is NOT the built-in
    # (the API's lowercasing-before-store is what makes stored hex
    # canonical — pin the renderer's own contract here).
    colors = {k: v.upper() for k, v in theming.BUILTIN_COLORS.items()}
    assert theming.theme_style_tag(colors) != ""


def test_theme_style_tag_one_changed_carries_all_nine_in_order() -> None:
    """A single non-built-in color still emits ALL 9 variables, in
    ``COLOR_FIELDS`` order, with the exact tag shape (no whitespace).
    Phase 92 (task 01): the tag carries ``--grid-line:#4a2626;`` between
    ``--line`` and ``--brand`` (the 9th identity variable — the
    background grid texture)."""
    colors = dict(theming.BUILTIN_COLORS)
    colors["brand"] = "#818cf8"
    tag = theming.theme_style_tag(colors)
    assert tag == (
        '<style id="bor-theme">:root{'
        "--bg:#0f0a0a;--surface:#1a0f0f;--ink:#f0e6e6;--ink-soft:#b8a8a8;"
        "--line:#2d1a1a;--grid-line:#4a2626;--brand:#818cf8;"
        "--brand-soft:#2d0a0a;--brand-ink:#fca5a5;"
        "}</style>"
    )
    # The changed value lands under the dashed CSS name…
    assert "--brand:#818cf8;" in tag
    # …and the underscored field (ink_soft) renders as --ink-soft.
    assert "--ink-soft:#b8a8a8;" in tag
    assert "--ink_soft" not in tag


def test_theme_style_tag_multiple_changed() -> None:
    """Two changed colors: both values present, the rest built-in, order
    unchanged (the tag is a complete :root override — the page never
    mixes a partial palette)."""
    colors = dict(theming.BUILTIN_COLORS)
    colors["bg"] = "#0a0e1a"
    colors["brand_ink"] = "#c7d2fe"
    tag = theming.theme_style_tag(colors)
    assert tag.startswith('<style id="bor-theme">:root{--bg:#0a0e1a;')
    assert "--brand-ink:#c7d2fe;" in tag
    assert tag.endswith("}</style>")
    # The order of the 9 dashed names is the COLOR_FIELDS order.
    names = re.findall(r"--([a-z-]+):", tag)
    assert names == [k.replace("_", "-") for k in theming.COLOR_FIELDS]


# ---------- inject_theme (pure — task 02's injection helper) ----------

_HEAD_HTML = "<html><head><title>t</title></head><body><p>b</p></body></html>"


def test_inject_theme_empty_tag_is_identity() -> None:
    """``tag == ""`` (the unset / "defaults saved" deployment — what
    ``theme_style_tag" returns for all-built-in colors) → the html is
    returned EXACTLY as passed in, byte for byte (B4's no-op
    contract)."""
    assert theming.inject_theme(_HEAD_HTML, "") == _HEAD_HTML
    # Whitespace is NOT an empty tag — a real tag is always inserted.
    assert theming.inject_theme(_HEAD_HTML, " ") != _HEAD_HTML


def test_inject_theme_missing_head_is_identity() -> None:
    """No ``</head>`` occurrence → unchanged (nothing to anchor to);
    the empty string (no ``</head>`` either) is identity too."""
    tag = '<style id="bor-theme">:root{--bg:#111111;}</style>'
    html = "<html><body>no head</body></html>"
    assert theming.inject_theme(html, tag) == html
    assert theming.inject_theme("", tag) == ""


def test_inject_theme_exact_placement_before_first_head_close() -> None:
    """The tag lands with a leading newline immediately BEFORE the
    first ``</head>`` — nothing between the tag and the close, nothing
    moved after it."""
    tag = '<style id="bor-theme">:root{--bg:#111111;}</style>'
    html = "<html><head><title>t</title></head><body>after</body></html>"
    assert theming.inject_theme(html, tag) == (
        "<html><head><title>t</title>\n" + tag + "</head><body>after</body></html>"
    )
    # A LATER ``</head>``-shaped stretch of text is not the anchor — the
    # FIRST occurrence wins (the one that closes the real head).
    html2 = "<head></head><script>if (x) { a() }</head></script></head>"
    assert theming.inject_theme(html2, tag) == (
        "<head>\n" + tag + "</head><script>if (x) { a() }</head></script></head>"
    )


def test_inject_theme_double_injection_is_idempotent() -> None:
    """The defensive idempotence rule keys on the id: once a
    ``id="bor-theme"`` tag is present the helper is the identity — the
    page can never carry two theme tags, even for a different tag."""
    tag = '<style id="bor-theme">:root{--bg:#111111;}</style>'
    once = theming.inject_theme(_HEAD_HTML, tag)
    assert once.count('id="bor-theme"') == 1
    assert theming.inject_theme(once, tag) == once
    other = '<style id="bor-theme">:root{--bg:#222222;}</style>'
    assert theming.inject_theme(once, other) == once


# ---------------------------------------------------------------------------
# Phase 91 (task 05, defect fix): theme_csp_hash — the CSP3 hash of the
# inline tag's content (the phase-82 CSP would otherwise BLOCK the tag
# in every real browser; the caching middleware publishes the hash as a
# style-src exemption on themed HTML pages only).
# ---------------------------------------------------------------------------


def test_theme_csp_hash_empty_tag_is_empty_string() -> None:
    """No tag (unset/defaults deployment) → no hash — the plain A1
    policy stands and the header stays byte-identical to pre-91."""
    assert theming.theme_csp_hash("") == ""


def test_theme_csp_hash_is_sha256_of_the_tag_content() -> None:
    """CSP3 §13.4: the hash covers the character data BETWEEN the tags
    (the ``:root{…}`` declarations — the rendered content carries no
    leading/trailing whitespace, so no stripping applies), base64
    after SHA-256, ``sha256-`` prefixed."""
    tag = '<style id="bor-theme">:root{--bg:#111111}</style>'
    expected = "sha256-" + base64.b64encode(
        hashlib.sha256(b":root{--bg:#111111}").digest()
    ).decode("ascii")
    assert theming.theme_csp_hash(tag) == expected


def test_theme_csp_hash_changes_with_the_palette() -> None:
    """A different palette → a different hash: the browser keeps
    blocking the OLD tag once the theme changes (the exemption always
    matches exactly the served bytes, never a stale palette)."""
    colors = dict(theming.BUILTIN_COLORS)
    colors["brand"] = "#818cf8"
    first = theming.theme_csp_hash(theming.theme_style_tag(colors))
    colors["brand"] = "#22c55e"
    second = theming.theme_csp_hash(theming.theme_style_tag(colors))
    assert first
    assert first != second
    assert first.startswith("sha256-")
    assert second.startswith("sha256-")