rune/tests/test_layout_obligations.py

"""test_layout_obligations.py — SCAFFOLD-TRANCHE-004 §31 test plan (A-H)."""

import os
import sys

import pytest

sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))

from rune import construction_decision as cd  # noqa: E402
from rune import layout_contract as lc  # noqa: E402
from rune import scaffold as sc  # noqa: E402
from rune import structural_store as ss  # noqa: E402
from rune import toolchain as tc  # noqa: E402


def _doc_with_layouts():
    doc = ss.new_doc()
    lc.define_region(doc, "footer-bar", provenance="scaffold", evidence_refs=["issue-105"])
    lc.define_region(doc, "header", provenance="user")
    # version display: scaffold-provenance (NOT user-locked — §21 status)
    lc.bind_component(
        doc,
        "version_display",
        "footer-bar",
        provenance="scaffold",
        order=0,
        evidence_ref="issue-105",
        implementation="src/rune/rune_tui.py:VersionLabel",
    )
    # a user-locked element for authority tests
    lc.bind_component(doc, "status_bar", "footer-bar", lock=True, provenance="user", order=1, evidence_ref="user-2026")
    return doc


def _need(**kw):
    d = dict(
        need_id="n",
        objective="tweak footer",
        origin="builder",
        constraints={},
        evidence_refs=["x"],
        approval_context="covered by contract",
    )
    d.update(kw)
    return cd.Need(**d)


# A. affected UI component pulls its Layout Contract into obligations
def test_a_ui_component_inherits_layout_obligation():
    doc = _doc_with_layouts()
    obs = cd.layout_obligations_for(doc, ["ui:version_display"])
    assert len(obs) == 1
    o = obs[0]
    assert o["component"] == "ui:version_display"
    assert o["region"] == "footer-bar"
    assert o["lock"] is False
    assert "layout_contract_check must PASS" in o["verification"]


# B. unrelated backend change inherits NO layout obligations
def test_b_backend_change_no_layout_obligations():
    doc = _doc_with_layouts()
    assert cd.layout_obligations_for(doc, ["module:memory_store"]) == []
    assert cd.layout_obligations_for(doc, ["capability:exporter"]) == []


def test_b2_implementation_path_match_pulls_contract():
    doc = _doc_with_layouts()
    obs = cd.layout_obligations_for(doc, ["src/rune/rune_tui.py"])
    assert any(o["component"] == "ui:version_display" for o in obs)


# C. FLEXIBLE layout obligation carried correctly
def test_c_flexible_obligation():
    doc = _doc_with_layouts()
    s = sc.Scaffold("/tmp/never-required", "x")
    o = s.layout_obligations(doc, ["ui:version_display"])[0]
    assert o["lock"] is False
    assert "movable only via authorized layout amendment" in o["obligation"]
    assert o["verification"] == "layout_contract_check must PASS"


# D. USER-LOCKED layout obligation blocks unauthorized change
def test_d_user_locked_obligation_blocks():
    doc = _doc_with_layouts()
    s = sc.Scaffold("/tmp/never-required", "x")
    obs = s.layout_obligations(doc, ["ui:status_bar"])
    assert len(obs) == 1
    o = obs[0]
    assert o["lock"] is True
    assert "USER-LOCKED" in o["obligation"]
    assert "explicit user authorization" in o["obligation"]
    assert "USER-LOCKED placement unchanged" in o["verification"]
    # and the live-path approval gate fires for locked surfaces
    gate = cd.needs_user_approval(
        "ADAPT_EXISTING",
        tc.resolve_toolchain(tc.ToolchainConstraints(existing_language="python")),
        obs,
        _need(approval_context=""),
    )
    assert gate["required"] is True
    assert "USER-LOCKED" in gate["reasons"][0]


# E. user-authorized layout amendment passes
def test_e_user_authorized_amendment_passes():
    doc = _doc_with_layouts()
    lc.amend_layout_contract(
        doc,
        "status_bar",
        new_region="header",
        authorized_by="user",
        reason="user reposition",
        evidence_ref="user-2026-09-13",
    )
    # contract follows the user's explicit change
    e = ss.entity(doc, "layout:ui:status_bar")
    assert e["identities"]["region"] == "header"
    # obligation now reflects the amended placement
    s = sc.Scaffold("/tmp/never-required", "x")
    obs = s.layout_obligations(doc, ["ui:status_bar"])
    assert obs[0]["region"] == "header"


# F. unavailable layout adapter remains UNKNOWN — never PASS
def test_f_unknown_never_pass():
    doc = _doc_with_layouts()
    result = lc.check_layout(doc, {})  # no adapter observations
    assert result["verdict"] == "UNKNOWN"
    assert all(c["verdict"] == "UNKNOWN" for c in result["checks"])


# G. drift does NOT rewrite USER-LOCKED intent
def test_g_drift_preserves_user_locked():
    doc = _doc_with_layouts()
    violating = {"ui:status_bar": {"region": "header", "order": 0}}
    out = lc.layout_drift(doc, violating)
    assert out["gate"] == "FAIL"
    e = ss.entity(doc, "layout:ui:status_bar")
    assert e["identities"]["region"] == "footer-bar"  # user intent preserved
    assert e["status"] == "DRIFTING"
    assert e["identities"]["lock"] is True
    # maintenance item records the violation for user review
    assert ss.entity(doc, "maintenance:layout-drift-ui:status_bar") is not None


# H. version-display stays scaffold-provenance until explicit confirmation
def test_h_version_display_not_user_locked():
    doc = _doc_with_layouts()
    e = ss.entity(doc, "layout:ui:version_display")
    assert e["identities"]["provenance"] == "scaffold"
    assert e["identities"]["lock"] is False  # pending user confirmation (§21)
    # any attempt to lock it without user provenance is refused
    with pytest.raises(ValueError, match="user provenance"):
        lc.bind_component(doc, "version_display", "footer-bar", lock=True, provenance="builder")