bvandeusenandClaude Opus 5.5
0e658bf275
Seven more test files: docstrings and comments state the property and its reason, the SQL-twin note states why `\m` and not `\b` without the install it broke, and fixture provenance says "real near-miss queries" rather than naming the spike that collected them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
247 lines
9.3 KiB
Python
247 lines
9.3 KiB
Python
"""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 scribe.mcp.tools import lessons as mcp_lessons
|
|
from scribe.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 scribe.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 scribe import app as app_module
|
|
|
|
src = inspect.getsource(app_module)
|
|
assert "from scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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 scribe.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
|