Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

41.1 KB
Raw Blame
"""The three-way reconcile behind "Update from device".

Baseline (the generated body recorded at the last sync) / current (the body the
user has now) / new (freshly generated from the live device). The contract:

* user-only edits are preserved, identical changes never conflict;
* untouched facts where the device moved are applied without asking;
* a fact both sides changed is a conflict the user resolves (keep / device /
  custom), and the resolution is what lands in the merged body;
* the generated sections are reconciled whole; user sections never move a
  character;
* a missing baseline is conservative: never a silent overwrite.
"""

import time
from datetime import date
from types import SimpleNamespace

import yaml

from app.services import doc_template as t
from app.services.doc_reconcile import (
    AUTO,
    CUSTOM,
    DEVICE,
    KEEP,
    SAME,
    Resolution,
    _heading_level,
    _parse_heading,
    _row_from_line,
    preview_id,
    reconcile,
    split_blocks,
)


# What the template reads off a row.
def _device(**overrides):
    base = dict(
        id="dev-1",
        label="homelabcluster",
        friendly_name=None,
        hostname="homelabcluster.example.lan",
        ip="192.168.10.20",
        mac="00:11:32:aa:bb:cc",
        ieee_address=None,
        os="Debian 12",
        vendor="Intel",
        model="N100",
        type="server",
        suggested_type=None,
        services=[
            {"port": 443, "protocol": "tcp", "service_name": "https", "category": "management"},
            {"port": 22, "protocol": "tcp", "service_name": "ssh"},
        ],
        properties=[{"key": "Serial", "value": "ABC123", "icon": None, "visible": True}],
        cpu_count=4,
        cpu_model="N100",
        ram_gb=16.0,
        disk_gb=2000.0,
        check_method="ping",
        check_target="-",
        discovery_source="arp",
        discovery_sources=["arp"],
        discovered_at=None,
        notes="",
        rack=None,
        zone_label="Homelab",
        connections=["switch-01"],
    )
    base.update(overrides)
    return SimpleNamespace(**base)


def _body(device, *, today=None) -> str:
    return t.render_device_document(device, today=today or date(2026, 3, 4))


def _run(current_dev, device, *, baseline=None, snapshot=None, resolutions=None):
    """Reconcile the document generated for current_dev against the live device."""
    if baseline is None:
        baseline = _body(current_dev)
    if snapshot is None:
        snapshot = t.facts_snapshot(current_dev)
    return reconcile(
        current=_body(current_dev),
        new=_body(device),
        baseline_body=baseline,
        snapshot=snapshot,
        resolutions=resolutions,
    )


def _by_id(changes):
    return {c.id: c for c in changes}


def _after(body, marker):
    """Everything from the marker line to the end."""
    start = body.find(marker)
    return body[start:] if start >= 0 else ""


# ── no change ───────────────────────────────────────────────────────────────


def test_stable_device_is_a_noop():
    result = _run(_device(), _device())
    assert all(c.status == SAME for c in result.changes)
    assert result.conflicts == []
    assert result.summary == []
    assert result.proposed_body == _body(_device())


# ── safe auto-updates ───────────────────────────────────────────────────────


def test_untouched_ip_is_applied_automatically():
    result = _run(_device(), _device(ip="192.168.10.25"))
    by_id = _by_id(result.changes)

    assert by_id["device-info.IP"].status == AUTO
    ip = by_id["device-info.IP"]
    assert "IP address updated to 192.168.10.25" in result.summary
    assert ip.previous == "192.168.10.20"

    assert by_id["device-info.Hostname"].status == SAME
    assert by_id["device-info.Hostname"].documented == "homelabcluster.example.lan"
    assert not result.conflicts

    assert "| IP | 192.168.10.25 |" in result.proposed_body
    # The service URL follows the IP, and is applied just as silently.
    assert "https://192.168.10.25" in result.proposed_body
    # User-owned sections come through byte for byte.
    assert _after(result.proposed_body, "## Configuration") == _after(_body(_device()), "## Configuration")


def test_device_info_ip_update_preserves_table_layout_and_empty_cells():
    """A device-only update must not re-render its user's table."""
    baseline = _body(_device())
    current = (
        baseline.replace("| | |\n|---|---|", "| Field | Value |\n|:------|-----:|")
        .replace("| IP | 192.168.10.20 |", "| IP     | 192.168.10.20     |")
        .replace("| OS | Debian 12 |", "| OS | |")
        .replace("| Status check | `ping` → `-` |", "| Status check | `ping` → `-` |\n\n_table note_")
    )
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )

    expected = current.replace("192.168.10.20", "192.168.10.25", 1)
    assert _after(result.proposed_body, "## Device Information").split("### Hardware", 1)[0] == (
        _after(expected, "## Device Information").split("### Hardware", 1)[0]
    )
    assert "| Field | Value |\n|:------|-----:|" in result.proposed_body
    assert "| OS | |" in result.proposed_body


def test_deleted_os_row_stays_absent_until_device_restore_is_approved():
    baseline = _body(_device())
    current = baseline.replace("| OS | Debian 12 |\n", "")

    unchanged = reconcile(
        current, baseline, baseline_body=baseline, snapshot=t.facts_snapshot(_device())
    )
    assert _by_id(unchanged.changes)["device-info.OS"].status == SAME
    assert unchanged.proposed_body == current

    changed = reconcile(
        current,
        _body(_device(os="Debian 13")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert _by_id(changed.changes)["device-info.OS"].status == "conflict"
    assert changed.proposed_body == current

    restored = reconcile(
        current,
        _body(_device(os="Debian 13")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="device-info.OS", choice=DEVICE)],
    )
    assert "| OS | Debian 13 |" in restored.proposed_body


def test_user_edit_is_kept_when_device_unchanged():
    current = _body(_device()).replace("| OS | Debian 12 |", "| OS | Debian 12 (tuned) |")
    snapshot = t.facts_snapshot(_device())
    result = reconcile(current, _body(_device()), baseline_body=_body(_device()), snapshot=snapshot)
    by_id = _by_id(result.changes)

    assert by_id["device-info.OS"].status == SAME
    assert "Debian 12 (tuned)" in result.proposed_body
    assert not result.conflicts


def test_identical_change_never_conflicts():
    # The user wrote the device's *new* value before the sync.
    current = _body(_device()).replace("| IP | 192.168.10.20 |", "| IP | 192.168.10.25 |")
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device()), snapshot=t.facts_snapshot(_device()))
    assert result.conflicts == []
    assert _by_id(result.changes)["device-info.IP"].status == SAME
    assert "| IP | 192.168.10.25 |" in result.proposed_body
    assert _after(result.proposed_body, "## Configuration") == _after(current, "## Configuration")


# ── conflicts and resolutions ───────────────────────────────────────────────


def test_both_sides_changed_is_a_conflict():
    current = _body(_device()).replace("| IP | 192.168.10.20 |", "| IP | 10.0.0.9 |")
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device()), snapshot=t.facts_snapshot(_device()))
    by_id = _by_id(result.changes)
    assert by_id["device-info.IP"].status == "conflict"
    assert [c.id for c in result.conflicts] == ["device-info.IP"]
    # Undecided conflicts keep the user's text in the draft.
    assert "| IP | 10.0.0.9 |" in result.proposed_body


def test_keep_resolution_keeps_user_text():
    current = _body(_device()).replace("| IP | 192.168.10.20 |", "| IP | 10.0.0.9 |")
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device()), snapshot=t.facts_snapshot(_device()), resolutions=[Resolution(id="device-info.IP", choice=KEEP)])
    assert "| IP | 10.0.0.9 |" in result.proposed_body
    assert "IP address kept as written" in result.summary
    assert result.unresolved == []


def test_device_resolution_takes_device_value():
    current = _body(_device()).replace("| IP | 192.168.10.20 |", "| IP | 10.0.0.9 |")
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device()), snapshot=t.facts_snapshot(_device()), resolutions=[Resolution(id="device-info.IP", choice=DEVICE)])
    assert "| IP | 192.168.10.25 |" in result.proposed_body


def test_escaped_pipe_ip_row_keeps_its_shape_for_device_and_custom_resolution():
    baseline = _body(_device())
    current = baseline.replace(
        "| IP | 192.168.10.20 |", "| IP   | nas.example \\| backup  |"
    )
    new = _body(_device(ip="192.168.10.25"))

    device = reconcile(
        current,
        new,
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="device-info.IP", choice=DEVICE)],
    )
    assert "| IP   | 192.168.10.25  |" in device.proposed_body

    custom = reconcile(
        current,
        new,
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="device-info.IP", choice=CUSTOM, custom="manual | route")],
    )
    assert "| IP   | manual \\| route  |" in custom.proposed_body


def test_custom_resolution_uses_user_text_and_escapes_it():
    current = _body(_device()).replace("| IP | 192.168.10.20 |", "| IP | 10.0.0.9 |")
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device()), snapshot=t.facts_snapshot(_device()), resolutions=[Resolution(id="device-info.IP", choice=CUSTOM, custom="10.0.0.9 (jump host)")])
    assert "| IP | 10.0.0.9 (jump host) |" in result.proposed_body
    assert "IP address set from your text" in result.summary


# ── the regression scenario from the issue ──────────────────────────────────


def test_hostname_change_suppresses_repeat_ip_notice():
    """Device hostname lands *once*; the untouched IP is not re-asked."""
    snapshot = t.facts_snapshot(_device(ip="192.168.10.20", hostname="old.example.lan"))
    baseline = _body(_device(ip="192.168.10.20", hostname="old.example.lan"))
    current = baseline  # generated at that time, untouched since
    result = reconcile(current, _body(_device(ip="192.168.10.25", hostname="homelabcluster.example.lan")), baseline_body=baseline, snapshot=snapshot)
    by_id = _by_id(result.changes)

    assert by_id["device-info.Hostname"].status == AUTO
    assert by_id["device-info.IP"].status == AUTO  # safe: never touched
    assert [c.id for c in result.conflicts] == []


def test_keeping_a_new_ip_acknowledges_it_once_and_warns_again_on_next_change():
    """A KEEP records the *device's* value as baseline, so the next device change
    asks again — acknowledgement is not permanent blindness."""
    # The doc carries a deliberate user value, so a device IP move is a conflict.
    current = _body(_device(ip="192.168.10.20")).replace("| IP | 192.168.10.20 |", "| IP | 192.168.10.20 (primary) |")
    baseline = _body(_device(ip="192.168.10.20"))
    snapshot = t.facts_snapshot(_device(ip="192.168.10.20"))

    # Device moved to .25, the user keeps their own entry.
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="device-info.IP", choice=KEEP)])
    assert result.unresolved == []
    merged = result.proposed_body
    assert "| IP | 192.168.10.20 (primary) |" in merged

    # Nothing changed since: no repeat warning.
    steady = reconcile(merged, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device(ip="192.168.10.25")), snapshot=t.facts_snapshot(_device(ip="192.168.10.25")))
    assert steady.conflicts == []
    assert "| IP | 192.168.10.20 (primary) |" in steady.proposed_body

    # The device moves again → the kept value is in question once more.
    later = reconcile(merged, _body(_device(ip="192.168.10.30")), baseline_body=_body(_device(ip="192.168.10.25")), snapshot=t.facts_snapshot(_device(ip="192.168.10.25")))
    assert [c.id for c in later.conflicts] == ["device-info.IP"]


# ── whole sections ──────────────────────────────────────────────────────────


def test_untouched_hardware_section_is_replaced_wholesale():
    result = _run(_device(), _device(cpu_model="N200"))
    by_id = _by_id(result.changes)
    assert by_id["section.Hardware"].status == AUTO
    assert "N200" in result.proposed_body
    assert _after(result.proposed_body, "## Configuration") == _after(_body(_device()), "## Configuration")


def test_a_section_summary_names_the_section_instead_of_quoting_it():
    # A whole table collapsed onto one summary line reads as noise.
    result = _run(_device(), _device(cpu_model="N200"))
    assert result.summary == ["Hardware updated from the device"]


def test_a_dropped_section_is_summarised_as_removed():
    baseline = _body(_device())
    result = reconcile(
        baseline, _body(_device(properties=[])), baseline_body=baseline, snapshot=t.facts_snapshot(_device())
    )
    assert result.summary == ["Properties removed"]


def test_section_conflict_resolves_three_ways():
    current = _body(_device()).replace(
        "| CPU | RAM | Disk |",
        "| CPU | RAM | Disk |\n|---|---|---|\n| manual | row | here |",
    )
    baseline = _body(_device())
    snapshot = t.facts_snapshot(_device())
    new = _body(_device(cpu_model="N200"))

    keep = reconcile(current, new, baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="section.Hardware", choice=KEEP)])
    assert "| manual | row | here |" in keep.proposed_body

    take = reconcile(current, new, baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="section.Hardware", choice=DEVICE)])
    assert "| manual | row | here |" not in take.proposed_body
    assert "N200" in take.proposed_body

    custom = reconcile(current, new, baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="section.Hardware", choice=CUSTOM, custom="| A | B | C |")])
    assert "| A | B | C |" in custom.proposed_body


def test_custom_section_text_never_collides_with_internal_actions():
    baseline = _body(_device())
    current = baseline.replace("| CPU | RAM | Disk |", "manual hardware notes")
    new = _body(_device(cpu_model="N200"))

    for custom in ("remove", "skip"):
        result = reconcile(
            current,
            new,
            baseline_body=baseline,
            snapshot=t.facts_snapshot(_device()),
            resolutions=[Resolution(id="section.Hardware", choice=CUSTOM, custom=custom)],
        )
        section = _after(result.proposed_body, "### Hardware").split("### Properties", 1)[0]
        assert custom in section
        assert "N200" not in section

    empty = reconcile(
        current,
        new,
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="section.Hardware", choice=CUSTOM, custom="")],
    )
    section = _after(empty.proposed_body, "### Hardware").split("### Properties", 1)[0]
    assert section.strip() == "### Hardware"


def test_user_sections_never_touched():
    current = _body(_device())
    edited = current.replace("## Notes", "## Notes\n\n_Every byte here is the user's._")
    result = reconcile(
        edited,
        _body(_device(ip="192.168.10.25", cpu_model="N200")),
        baseline_body=current,
        snapshot=t.facts_snapshot(_device()),
    )
    tail = _after(edited, "## Notes")
    assert _after(result.proposed_body, "## Notes") == tail
    assert "## Operations" in result.proposed_body and "### Backup" in result.proposed_body


def test_unknown_baseline_never_recreates_deleted_device_info_table():
    """Legacy documents need an explicit review before restoring a missing table."""
    generated = _body(_device())
    start = generated.index("## Device Information")
    end = generated.index("### Hardware")
    current = generated[:start] + generated[end:]

    preview = reconcile(current, generated, baseline_body=None, snapshot=None)
    table_change = _by_id(preview.changes)["device-info"]
    assert table_change.status == "conflict"
    assert preview.unresolved == [table_change]
    assert "## Device Information" not in preview.proposed_body

    reviewed = reconcile(
        current,
        generated,
        baseline_body=None,
        snapshot=None,
        resolutions=[Resolution(id="device-info", choice=DEVICE)],
    )
    assert "## Device Information" in reviewed.proposed_body


# ── ambiguous duplicates ────────────────────────────────────────────────


def test_duplicate_ip_row_no_device_change_preserves_both():
    baseline = _body(_device())
    current = baseline.replace(
        "| IP | 192.168.10.20 |",
        "| IP | 192.168.10.20 |\n| IP | manual-secondary |",
    )
    result = reconcile(
        current,
        _body(_device()),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert result.conflicts == []
    assert result.proposed_body.count("| IP |") == 2
    assert "| IP | 192.168.10.20 |" in result.proposed_body
    assert "| IP | manual-secondary |" in result.proposed_body


def test_duplicate_ip_row_prepended_no_device_change_preserves_both():
    baseline = _body(_device())
    current = baseline.replace(
        "| IP | 192.168.10.20 |",
        "| IP | manual-first |\n| IP | 192.168.10.20 |",
    )
    result = reconcile(
        current,
        _body(_device()),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert result.conflicts == []
    assert result.proposed_body.count("| IP |") == 2
    assert "| IP | manual-first |" in result.proposed_body
    assert "| IP | 192.168.10.20 |" in result.proposed_body


def test_duplicate_ip_row_device_change_surfaces_conflict():
    baseline = _body(_device())
    current = baseline.replace(
        "| IP | 192.168.10.20 |",
        "| IP | 192.168.10.20 |\n| IP | manual-secondary |",
    )
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert "device-info.IP" in [c.id for c in result.conflicts]
    # Neither row is touched silently; both are preserved verbatim.
    info_rows = [line for line in result.proposed_body.splitlines() if line.startswith("| IP |")]
    assert info_rows == ["| IP | 192.168.10.20 |", "| IP | manual-secondary |"]


def test_duplicate_ip_row_device_resolution_updates_first_only():
    baseline = _body(_device())
    current = baseline.replace(
        "| IP | 192.168.10.20 |",
        "| IP | 192.168.10.20 |\n| IP | manual-secondary |",
    )
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="device-info.IP", choice=DEVICE)],
    )
    rows = [line for line in result.proposed_body.splitlines() if line.startswith("| IP |")]
    assert rows == ["| IP | 192.168.10.25 |", "| IP | manual-secondary |"]


def test_duplicate_hardware_no_device_change_preserves_both():
    baseline = _body(_device())
    current = baseline + "\n### Hardware\n\nMANUAL DISK RECOVERY PROCEDURE\n"
    result = reconcile(
        current,
        _body(_device()),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert result.conflicts == []
    assert result.proposed_body.count("### Hardware") == 2
    assert "MANUAL DISK RECOVERY PROCEDURE" in result.proposed_body


def test_duplicate_hardware_prepended_no_device_change_preserves_both():
    baseline = _body(_device())
    hw_offset = baseline.index("### Hardware")
    current = (
        baseline[:hw_offset]
        + "### Hardware\n\nMANUAL DISK RECOVERY PROCEDURE\n\n"
        + baseline[hw_offset:]
    )
    result = reconcile(
        current,
        _body(_device()),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert result.conflicts == []
    assert result.proposed_body.count("### Hardware") == 2
    assert "MANUAL DISK RECOVERY PROCEDURE" in result.proposed_body


def test_duplicate_hardware_device_change_surfaces_conflict():
    baseline = _body(_device())
    current = baseline + "\n### Hardware\n\nMANUAL DISK RECOVERY PROCEDURE\n"
    result = reconcile(
        current,
        _body(_device(cpu_model="N200")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert "section.Hardware" in [c.id for c in result.conflicts]
    # No auto-edit to the guessed-first block; both are preserved untouched.
    assert "MANUAL DISK RECOVERY PROCEDURE" in result.proposed_body
    assert "N200" not in result.proposed_body


def test_duplicate_hardware_resolution_updates_generated_block_only():
    baseline = _body(_device())
    current = baseline + "\n### Hardware\n\nMANUAL DISK RECOVERY PROCEDURE\n"
    result = reconcile(
        current,
        _body(_device(cpu_model="N200")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="section.Hardware", choice=DEVICE)],
    )
    assert result.proposed_body.count("### Hardware") == 2
    assert "N200" in result.proposed_body
    assert "MANUAL DISK RECOVERY PROCEDURE" in result.proposed_body


def test_duplicate_hardware_custom_resolution_updates_generated_block_only():
    baseline = _body(_device())
    current = baseline + "\n### Hardware\n\nMANUAL DISK RECOVERY PROCEDURE\n"
    result = reconcile(
        current,
        _body(_device(cpu_model="N200")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="section.Hardware", choice=CUSTOM, custom="| A | B | C |")],
    )
    assert result.proposed_body.count("### Hardware") == 2
    assert "| A | B | C |" in result.proposed_body
    assert "MANUAL DISK RECOVERY PROCEDURE" in result.proposed_body


def test_duplicate_hardware_prepended_device_change_surfaces_conflict():
    baseline = _body(_device())
    hw_offset = baseline.index("### Hardware")
    current = (
        baseline[:hw_offset]
        + "### Hardware\n\nMANUAL DISK RECOVERY PROCEDURE\n\n"
        + baseline[hw_offset:]
    )
    result = reconcile(
        current,
        _body(_device(cpu_model="N200")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert "section.Hardware" in [c.id for c in result.conflicts]
    assert "N200" not in result.proposed_body
    assert "MANUAL DISK RECOVERY PROCEDURE" in result.proposed_body


def _duplicate_device_info(current, manual_os=None):
    """Duplicate the whole generated Device Information block in the body.

    The copy goes BEFORE the original; ``manual_os`` marks it as the user's own
    table so a fix that edits the guessed-first copy on its own is testable.
    """
    heading = "## Device Information"
    start = current.index(heading)
    end = current.index("### Hardware")
    info_block = current[start:end]
    if manual_os is not None:
        info_block = info_block.replace("| OS | Debian 12 |", f"| OS | {manual_os} |")
    return current[:start] + info_block + info_block + current[end:]


def test_duplicate_device_info_heading_ip_change_surfaces_conflict():
    baseline = _body(_device())
    current = _duplicate_device_info(baseline)
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert "device-info.IP" in [c.id for c in result.conflicts]
    # No silent auto-edit of the guessed-first table; both keep their value.
    assert result.proposed_body.count("## Device Information") == 2
    assert result.proposed_body.count("| IP | 192.168.10.20 |") == 2
    assert "| IP | 192.168.10.25 |" not in result.proposed_body


def test_duplicate_device_info_heading_ip_resolution_updates_first_only():
    baseline = _body(_device())
    current = _duplicate_device_info(baseline)
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
        resolutions=[Resolution(id="device-info.IP", choice=KEEP)],
    )
    assert result.proposed_body.count("## Device Information") == 2
    assert result.proposed_body.count("| IP | 192.168.10.20 |") == 2


def test_duplicate_device_info_prepended_ip_change_surfaces_conflict():
    baseline = _body(_device())
    current = _duplicate_device_info(baseline, manual_os="Debian 12 (manual)")
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device()),
    )
    assert "device-info.IP" in [c.id for c in result.conflicts]
    assert result.proposed_body.count("## Device Information") == 2
    # The user-owned copy is the first one; it must not be silently edited.
    assert "| OS | Debian 12 (manual) |" in result.proposed_body
    assert "| IP | 192.168.10.25 |" not in result.proposed_body


# ── device name ─────────────────────────────────────────────────────────


def test_device_name_auto_and_conflict():
    baseline = _body(_device(label="nas-01"))
    snapshot = t.facts_snapshot(_device(label="nas-01"))
    new = _body(_device(label="nas-02"))
    current = baseline

    auto = reconcile(current, new, baseline_body=baseline, snapshot=snapshot)
    assert _by_id(auto.changes)["name"].status == AUTO
    assert 'title: "nas-02"' in auto.proposed_body
    assert "# nas-02\n" in auto.proposed_body

    renamed = current.replace("# nas-01", "# my-nas")
    conflict = reconcile(renamed, new, baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="name", choice=KEEP)])
    assert _by_id(conflict.changes)["name"].status == "conflict"
    assert "# my-nas" in conflict.proposed_body and "# nas-02" not in conflict.proposed_body


def test_ordinary_rename_follows_in_h1_and_title():
    baseline = _body(_device(label="nas-01"))
    result = reconcile(
        baseline,
        _body(_device(label="nas-02")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device(label="nas-01")),
    )
    by_id = _by_id(result.changes)
    assert by_id["name"].status == AUTO
    assert by_id["title"].status == AUTO
    assert 'title: "nas-02"' in result.proposed_body
    assert "# nas-02\n" in result.proposed_body


def test_independently_edited_title_survives_device_rename():
    """Finding 3: a manual frontmatter title must not be copied from the H1
    decision; the untouched H1 may follow the device while the manual title
    stays, surfaced as an explicit title conflict."""
    baseline = _body(_device(label="homelabcluster"))
    current = baseline.replace("title: homelabcluster", "title: Recovery Runbook")
    result = reconcile(
        current,
        _body(_device(label="new-name")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device(label="homelabcluster")),
    )
    by_id = _by_id(result.changes)
    # The untouched H1 follows the rename, the manual title does not.
    assert by_id["name"].status == AUTO
    assert by_id["title"].status == "conflict"
    assert "title" in [c.id for c in result.conflicts]
    assert "title: Recovery Runbook" in result.proposed_body
    assert "title: new-name" not in result.proposed_body
    assert "# new-name\n" in result.proposed_body


def test_title_conflict_resolves_keep_and_device():
    baseline = _body(_device(label="homelabcluster"))
    current = baseline.replace("title: homelabcluster", "title: Recovery Runbook")
    new = _body(_device(label="new-name"))
    snapshot = t.facts_snapshot(_device(label="homelabcluster"))

    keep = reconcile(current, new, baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="title", choice=KEEP)])
    assert "title: Recovery Runbook" in keep.proposed_body

    take = reconcile(current, new, baseline_body=baseline, snapshot=snapshot, resolutions=[Resolution(id="title", choice=DEVICE)])
    assert 'title: "new-name"' in take.proposed_body


def test_custom_title_with_yaml_syntax_is_serialized_semantically():
    baseline = _body(_device(label="homelabcluster"))
    current = baseline.replace(
        "title: homelabcluster", "title: Recovery Runbook\ncustom_frontmatter: 'keep: exact'"
    )
    new = _body(_device(label="new-name"))

    for title in ("Recovery: primary", "Recovery #1"):
        result = reconcile(
            current,
            new,
            baseline_body=baseline,
            snapshot=t.facts_snapshot(_device(label="homelabcluster")),
            resolutions=[Resolution(id="title", choice=CUSTOM, custom=title)],
        )
        frontmatter = result.proposed_body.split("---", 2)[1]
        assert yaml.safe_load(frontmatter)["title"] == title
        assert "custom_frontmatter: 'keep: exact'" in frontmatter


def test_title_scalar_replacement_removes_continuation_and_keep_preserves_frontmatter():
    baseline = _body(_device(label="homelabcluster"))
    current = baseline.replace(
        "title: homelabcluster",
        "title: |\n  Recovery Runbook\ncustom_frontmatter: 'keep: exact'",
    )
    new = _body(_device(label="new-name"))
    snapshot = t.facts_snapshot(_device(label="homelabcluster"))

    device = reconcile(
        current,
        new,
        baseline_body=baseline,
        snapshot=snapshot,
        resolutions=[Resolution(id="title", choice=DEVICE)],
    )
    frontmatter = device.proposed_body.split("---", 2)[1]
    assert yaml.safe_load(frontmatter)["title"] == "new-name"
    assert "Recovery Runbook" not in frontmatter
    assert "custom_frontmatter: 'keep: exact'" in frontmatter

    kept = reconcile(
        current,
        new,
        baseline_body=baseline,
        snapshot=snapshot,
        resolutions=[Resolution(id="title", choice=KEEP)],
    )
    assert kept.proposed_body.split("---", 2)[1] == current.split("---", 2)[1]


def test_title_replacement_removes_multiline_quoted_scalar():
    baseline = _body(_device(label="homelabcluster"))
    current = baseline.replace(
        "title: homelabcluster",
        'title: "Recovery\n  Runbook"\ncustom_frontmatter: \'keep: exact\'',
    )
    result = reconcile(
        current,
        _body(_device(label="new-name")),
        baseline_body=baseline,
        snapshot=t.facts_snapshot(_device(label="homelabcluster")),
        resolutions=[Resolution(id="title", choice=DEVICE)],
    )
    frontmatter = result.proposed_body.split("---", 2)[1]
    assert yaml.safe_load(frontmatter)["title"] == "new-name"
    assert "Recovery" not in frontmatter and "Runbook" not in frontmatter
    assert "custom_frontmatter: 'keep: exact'" in frontmatter


def test_new_properties_section_is_added_before_user_sections():
    plain = _device(properties=[])
    result = _run(plain, _device(properties=[{"key": "Serial", "value": "ABC123"}]))
    assert _by_id(result.changes)["section.Properties"].status == AUTO
    lines = result.proposed_body.splitlines()
    props_index = lines.index("### Properties")
    config_index = lines.index("## Configuration")
    assert props_index < config_index
    assert "| Serial | ABC123 |" in result.proposed_body


def test_unknown_history_never_recreates_deleted_generated_sections():
    generated = _body(_device())
    sections = (
        ("Hardware", "### Hardware", "### Properties"),
        ("Properties", "### Properties", "## Services"),
        ("Services", "## Services", "## Network"),
        ("Network", "## Network", "## Configuration"),
    )

    for name, heading, next_heading in sections:
        start = generated.index(heading)
        end = generated.index(next_heading, start)
        current = generated[:start] + generated[end:]
        result = reconcile(current, generated, baseline_body=None, snapshot=None)

        assert _by_id(result.changes)[f"section.{name}"].status == "conflict"
        assert heading not in result.proposed_body


def test_complete_baseline_can_add_a_new_generated_section():
    generated = _body(_device())
    start = generated.index("### Properties")
    end = generated.index("## Services", start)
    baseline = generated[:start] + generated[end:]
    result = reconcile(baseline, generated, baseline_body=baseline, snapshot=None)

    assert _by_id(result.changes)["section.Properties"].status == AUTO
    assert "### Properties" in result.proposed_body


def test_snapshot_proves_a_new_properties_section_can_be_added():
    generated = _body(_device())
    start = generated.index("### Properties")
    end = generated.index("## Services", start)
    current = generated[:start] + generated[end:]
    result = reconcile(
        current,
        generated,
        baseline_body=None,
        snapshot=t.facts_snapshot(_device(properties=[])),
    )

    assert _by_id(result.changes)["section.Properties"].status == AUTO
    assert "### Properties" in result.proposed_body


def test_snapshot_does_not_restore_deleted_services_without_a_baseline():
    generated = _body(_device())
    start = generated.index("## Services")
    end = generated.index("## Network", start)
    current = generated[:start] + generated[end:]
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=None,
        snapshot=t.facts_snapshot(_device()),
    )

    assert _by_id(result.changes)["section.Services"].status == "conflict"
    assert "## Services" not in result.proposed_body


def test_snapshot_does_not_restore_deleted_network_without_a_baseline():
    generated = _body(_device())
    start = generated.index("## Network")
    end = generated.index("## Configuration", start)
    current = generated[:start] + generated[end:]
    result = reconcile(
        current,
        _body(_device(ip="192.168.10.25")),
        baseline_body=None,
        snapshot=t.facts_snapshot(_device()),
    )

    assert _by_id(result.changes)["section.Network"].status == "conflict"
    assert "## Network" not in result.proposed_body


def test_untouched_removed_properties_are_dropped_automatically():
    # The complete baseline proves the section was device-owned and untouched.
    baseline = _body(_device())
    current = _body(_device())
    new = _body(_device(properties=[]))
    result = reconcile(current, new, baseline_body=baseline, snapshot=t.facts_snapshot(_device()))
    assert _by_id(result.changes)["section.Properties"].status == AUTO
    assert "### Properties" not in result.proposed_body


def test_edited_removed_properties_require_a_decision():
    baseline = _body(_device())
    current = baseline.replace("| Serial | ABC123 |", "| Serial | manual recovery token |")
    new = _body(_device(properties=[]))
    result = reconcile(current, new, baseline_body=baseline, snapshot=t.facts_snapshot(_device()))

    assert _by_id(result.changes)["section.Properties"].status == "conflict"
    assert "### Properties" in result.proposed_body
    assert "manual recovery token" in result.proposed_body


# ── conservatism and fingerprints ───────────────────────────────────────────


def test_missing_baseline_is_conservative_never_silent():
    """No baseline and no snapshot: a changed device still surfaces conflicts."""
    current = _body(_device())
    result = reconcile(current, _body(_device(ip="192.168.10.25")), baseline_body=None, snapshot=None)
    by_id = _by_id(result.changes)
    assert by_id["device-info.IP"].status == "conflict"
    # A stable device without a baseline is still quiet.
    stable = reconcile(current, _body(_device()), baseline_body=None, snapshot=None)
    assert stable.conflicts == []
    assert stable.proposed_body == current


def test_preview_id_binds_body_facts_and_timestamp():
    a = preview_id("2026-03-04T10:00:00Z", {"ip": "192.168.10.20"}, "# body")
    assert a == preview_id("2026-03-04T10:00:00Z", {"ip": "192.168.10.20"}, "# body")
    assert a != preview_id("2026-03-04T10:00:01Z", {"ip": "192.168.10.20"}, "# body")
    assert a != preview_id("2026-03-04T10:00:00Z", {"ip": "192.168.10.25"}, "# body")
    assert a != preview_id("2026-03-04T10:00:00Z", {"ip": "192.168.10.20"}, "# other")


def test_preview_id_binds_baseline_and_live_device():
    base = preview_id("2026-03-04T10:00:00Z", {"ip": "192.168.10.20"}, "# body")
    baseline = preview_id(
        "2026-03-04T10:00:00Z", {"ip": "192.168.10.20"}, "# body", baseline_body="# generated"
    )
    live = preview_id(
        "2026-03-04T10:00:00Z",
        {"ip": "192.168.10.20"},
        "# body",
        baseline_body="# generated",
        live={"facts": {"ip": "192.168.10.30"}, "context": {"zone_label": "lan"}, "generated": "# …"},
    )
    assert base != baseline
    assert baseline != live
    # A device that moved on between preview and apply changes the id.
    assert live != preview_id(
        "2026-03-04T10:00:00Z",
        {"ip": "192.168.10.20"},
        "# body",
        baseline_body="# generated",
        live={"facts": {"ip": "192.168.10.40"}, "context": {"zone_label": "lan"}, "generated": "# …"},
    )
    # A rendered-only change — same facts and context, different generated body.
    assert live != preview_id(
        "2026-03-04T10:00:00Z",
        {"ip": "192.168.10.20"},
        "# body",
        baseline_body="# generated",
        live={
            "facts": {"ip": "192.168.10.30"},
            "context": {"zone_label": "lan"},
            "generated": "# changed rendering",
        },
    )
    # Same device, context and generated body keep it stable.
    assert live == preview_id(
        "2026-03-04T10:00:00Z",
        {"ip": "192.168.10.20"},
        "# body",
        baseline_body="# generated",
        live={"facts": {"ip": "192.168.10.30"}, "context": {"zone_label": "lan"}, "generated": "# …"},
    )


def test_document_drift_clears_after_apply_style_refresh():
    """After applying, regenerating the document from the *new* snapshot stays quiet."""
    baseline = _body(_device())
    snapshot = t.facts_snapshot(_device())
    result = reconcile(baseline, _body(_device(ip="192.168.10.25")), baseline_body=baseline, snapshot=snapshot)
    merged = result.proposed_body
    # What a successful sync records: merged body + generated body + new facts.
    refreshed = reconcile(merged, _body(_device(ip="192.168.10.25")), baseline_body=_body(_device(ip="192.168.10.25")), snapshot=t.facts_snapshot(_device(ip="192.168.10.25")))
    assert refreshed.conflicts == []
    assert refreshed.proposed_body == merged


# ── line parsers (hand-rolled: the regexes they replace were quadratic) ─────


def test_parse_heading_reads_level_and_trimmed_name():
    assert _parse_heading("# Title") == (1, "Title")
    assert _parse_heading("##   Services  ") == (2, "Services")
    assert _parse_heading("###\tPort 80") == (3, "Port 80")
    assert _parse_heading("## ") == (2, "")
    assert _parse_heading("## a # b") == (2, "a # b")
    assert _parse_heading("# Title\n") == (1, "Title")


def test_parse_heading_rejects_non_headings():
    for line in ("", "#", "##", "#Title", "#### Too deep", " # Indented", "plain", "# a\nb"):
        assert _parse_heading(line) is None, line
        assert _heading_level(line) == 0, line


def test_row_from_line_reads_label_and_cell():
    assert _row_from_line("| IP | 192.168.1.1 |") == ("IP", "192.168.1.1")
    assert _row_from_line("|IP|192.168.1.1|") == ("IP", "192.168.1.1")
    assert _row_from_line("|  Host name  |   |") == ("Host name", "")
    assert _row_from_line("| a ||") == ("a", "")
    # Further pipes belong to the cell.
    assert _row_from_line("| Ports | 80 | 443 |") == ("Ports", "80 | 443")
    assert _row_from_line("| IP | 192.168.1.1 |\n") == ("IP", "192.168.1.1")


def test_row_from_line_rejects_non_rows():
    for line in (
        "",
        "|",
        "||",
        "| only one cell |",
        "|| empty label |",
        "|   | blank label |",
        "| --- | --- |",
        "| :-: | value |",
        "IP | 192.168.1.1 |",
        "| IP | 192.168.1.1",
        "| IP | a\nb |",
    ):
        assert _row_from_line(line) is None, line


def test_line_parsers_stay_linear_on_long_whitespace_runs():
    """CodeQL py/polynomial-redos: these inputs took seconds with the regexes."""
    pad = " " * 200_000
    start = time.perf_counter()
    assert _parse_heading(f"# {pad}x{pad}x") == (1, f"x{pad}x")
    assert _row_from_line(f"|{pad}a{pad}a{pad}|{pad}b{pad}b") is None
    assert _row_from_line(f"|{pad}a{pad}|{pad}b{pad}|") == ("a", "b")
    assert len(split_blocks(f"## {pad}x{pad}x\nbody")) == 1
    assert time.perf_counter() - start < 1.0