"""The REST door for lessons — the half the web UI can actually reach.

WHY THIS EXISTS AT ALL

The MCP tools are the surface an agent uses; the Vue app speaks REST. Without
this blueprint a lesson is a record a person cannot create, read, edit or
retire from the UI — a feature with no UI, failing at the door rather than in
the view.

WHAT THESE PIN

Three things a second door tends to get wrong, and one that is specific to this
kind:

  - PARITY. Both doors go through services/lessons.py, so the composed
    document is identical whichever one wrote it. A REST door that composed its
    own title would produce lessons that rank differently from the agent's, and
    the document IS what ranks.

  - ACL. Share-aware resolve, write as the owner — the pattern
    routes/snippets.py sets — so a shared editor isn't rejected by the
    owner-scoped service.

  - THE TRIGGER IS REFUSED WHEN EMPTY. This is the kind-specific one and the
    reason the door is not a thin wrapper. The service will happily store a
    lesson with no trigger: it saves, it reads correctly in every listing, and
    it never surfaces. There is nothing to notice afterwards — it looks exactly
    like a lesson that works. So the door refuses it at both create and update
    rather than handing back a record that looks finished.

  - THE REVERSE DIRECTION. `taught-by/<id>` answers "what was learned from this
    record", which the task body calls the direction that gets forgotten and
    arguably the more useful one.
"""
import inspect

import pytest


# ── parity: one composer, two doors ──────────────────────────────────────────


def test_both_doors_share_one_serializer():
    """A payload shape spelled once per door answers the two of them
    differently the first time a field is added."""
    from grimoire.mcp.tools import lessons as mcp_lessons
    from grimoire.services import lessons as lessons_svc

    assert mcp_lessons._to_dict is lessons_svc.lesson_to_dict


def test_the_rest_door_composes_nothing_itself():
    """Asserted on structure. The document is what ranks, so a door
    that built its own title would produce lessons that rank differently from
    the ones the agent writes."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes)
    # It may CALL the service's composer (the dedup gate needs the document),
    # but it must not assemble a title or a trigger line itself.
    assert "trigger_title" not in src
    assert "**When to apply:**" not in src
    assert "lessons_svc.lesson_document" in src, (
        "the dedup gate must hash the same document the service will store"
    )


def test_the_door_is_registered():
    """A blueprint nobody registers is a file, not a door."""
    from grimoire import app as app_module

    src = inspect.getsource(app_module)
    assert "from grimoire.routes.lessons import lessons_bp" in src
    assert "app.register_blueprint(lessons_bp)" in src


def test_the_blueprint_is_mounted_where_the_client_looks():
    from grimoire.routes.lessons import lessons_bp

    assert lessons_bp.url_prefix == "/api/lessons"


def test_the_reverse_lookup_is_registered_before_the_id_route():
    """Quart matches in registration order. The int converter protects
    `taught-by` today, but the ordering is what keeps that true if the
    converter is ever widened — the same care snippets' `/duplicates` takes."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes)
    assert src.index('"/taught-by/<int:record_id>"') < src.index(
        '"/<int:lesson_id>"'
    )


# ── the trigger is not optional at this door ─────────────────────────────────


def test_create_refuses_a_lesson_with_no_trigger():
    """The kind-specific guard. A triggerless lesson saves and never surfaces,
    and nothing about the stored record shows it."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes.create_lesson_route)
    assert "when_to_apply is required" in src
    assert "never reaches anyone" in src, (
        "the refusal must say WHY, or the next person reads it as a nag and "
        "removes it"
    )


def test_update_refuses_to_clear_the_trigger():
    """The other half. Creating without one is refused; emptying one later
    would reach the same broken state by a different path."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes.update_lesson_route)
    assert "cannot be cleared" in src


def test_the_subject_is_required_too():
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes.create_lesson_route)
    assert "what is required" in src


# ── ACL: the shared-access pattern, not a bare owner filter ──────────────────


@pytest.mark.parametrize(
    "handler", ["update_lesson_route", "delete_lesson_route"]
)
def test_writes_check_permission_and_act_as_the_owner(handler):
    """Resolve share-aware, then write as the owner — otherwise a shared
    editor is rejected by the owner-scoped service."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(getattr(routes, handler))
    assert "can_write_note" in src, f"{handler} does not check write permission"
    assert "note.user_id" in src, (
        f"{handler} writes as the caller rather than as the owner, which "
        f"rejects a legitimately shared editor"
    )


def test_no_handler_builds_its_own_owner_filter():
    """The access layer's actual failure mode: a route assembling its own
    `Note.user_id == uid` clause instead of going through the service and the
    access helpers. Passing `user_id=uid` INTO a service is the correct call
    and is not what this looks for."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes)
    assert "Note.user_id" not in src
    assert "select(" not in src, (
        "a route composing its own query has bypassed the access helpers"
    )


def test_delete_trashes_recoverably():
    """Every kind's delete is a trash, and the batch id is what restores it."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes.delete_lesson_route)
    assert "trash_svc.delete" in src
    assert "deleted_batch_id" in src


# ── the reverse direction ────────────────────────────────────────────────────


def test_the_reverse_lookup_reads_the_indexed_mirror():
    """Not by scanning bodies: `data[taught_by]` is JSONB with a GIN index
    (0070), which is the whole reason step 4 put the list there."""
    from grimoire.services import lessons as lessons_svc

    src = inspect.getsource(lessons_svc.lessons_taught_by)
    assert "path_exists" in src
    assert "SOURCES_KEY" in src


def test_the_reverse_lookup_is_share_aware():
    """It renders beside a record the caller can already see, so a lesson
    someone shared with them belongs in the list exactly as their own does."""
    from grimoire.services import lessons as lessons_svc

    src = inspect.getsource(lessons_svc.lessons_taught_by)
    assert "readable_notes_clause" in src
    assert "deleted_at" in src


def test_the_reverse_lookup_refuses_a_nonsense_id_rather_than_interpolating():
    """The jsonpath is built by formatting, so the id has to be an int before
    it gets near the expression."""
    from grimoire.services import lessons as lessons_svc

    src = inspect.getsource(lessons_svc.lessons_taught_by)
    assert "int(record_id)" in src


@pytest.mark.asyncio
async def test_a_bad_id_returns_nothing_and_raises_nothing():
    from grimoire.services.lessons import lessons_taught_by

    assert await lessons_taught_by(1, 0) == []
    assert await lessons_taught_by(1, -3) == []
    assert await lessons_taught_by(1, "not a number") == []


# ── the serializer speaks the vocabulary the caller wrote with ───────────────


def test_the_payload_reads_back_the_composed_fields():
    """A caller that wrote `when_to_apply` reads `when_to_apply` back, not a
    body it has to parse."""
    from tests.helpers import fake_lesson
    from grimoire.services.lessons import compose_body, lesson_to_dict

    what = "Read the job log before waiting longer"
    trigger = "a CI run has sat in_progress longer than its suite takes"
    note = fake_lesson(
        id=7,
        title=what,
        body=compose_body("The work is usually done.", trigger, [4181]),
        data={"what": what, "when_to_apply": trigger, "taught_by": [4181]},
        project_id=None,
        created_at=None,
        updated_at=None,
    )
    out = lesson_to_dict(note)
    assert out["what"] == what
    assert out["when_to_apply"] == trigger
    assert out["learned_from"] == [4181]
    # The insight comes back WITHOUT the lines compose_body added, so an edit
    # form round-trips instead of accumulating a copy of them per save.
    assert out["insight"] == "The work is usually done."
    assert "**When to apply:**" not in out["insight"]


def test_the_rest_guards_can_fail():
    """Shown turning red once."""
    from grimoire.routes import lessons as routes

    src = inspect.getsource(routes)
    assert "a phrase that is definitely not in this module" not in src
    assert "lessons_bp" in src