From 5e951935d9396fe9607cf068376a9e506c3cab47 Mon Sep 17 00:00:00 2001 From: Joshua Date: Fri, 18 Sep 2026 06:40:22 -0400 Subject: [PATCH] feat: complete_instance no-op if already done --- custom_components/nestquest/completion.py | 57 +++++++- tests/test_completion.py | 152 +++++++++++++++++++++- 2 files changed, 202 insertions(+), 7 deletions(-) diff --git a/custom_components/nestquest/completion.py b/custom_components/nestquest/completion.py index 94bbb46..87e6f93 100644 --- a/custom_components/nestquest/completion.py +++ b/custom_components/nestquest/completion.py @@ -4,11 +4,11 @@ Sits between the Feature 09 service gate and the typed :class:`~.dao_instances.CompletionEventsDao`: callers get actor-shape validation and the UTC occurred-at stamp here, and never talk to the DAO or SQL directly. This module is the only Feature-08 caller of -:meth:`~.dao_instances.CompletionEventsDao.append`. Completing and -un-completing an instance (no-op-if-already-done) arrive in later -tasks. Instance current state is derived from the latest event via -:func:`instance_state` (``open`` / ``done``); there is no status -column. +:meth:`~.dao_instances.CompletionEventsDao.append`. Completing an +instance (no-op if already done) is :func:`complete_instance`; +un-completing arrives in a later task. Instance current state is +derived from the latest event via :func:`instance_state` +(``open`` / ``done``); there is no status column. Actor policy matches the schema CHECKs (D-008): ``actor_source`` is ``'user'`` or ``'panel'`` only — never ``'service'``. ``'user'`` @@ -198,3 +198,50 @@ async def instance_state( f"event_type must be '{EVENT_COMPLETED}' or " f"'{EVENT_UNCOMPLETED}', got {latest.event_type!r}" ) + + +async def complete_instance( + database: NestQuestDatabase, + instance_id: int, + *, + actor_source: str, + actor_user_id: str | None = None, + actor_child_id: int | None = None, + now: datetime.datetime | None = None, + today: datetime.date | None = None, +) -> str: + """Append a completed event unless the instance is already done. + + Returns the derived state ``done``. An already-done instance is a + no-op: nothing is appended. Unknown ``instance_id`` raises + ValueError naming the field. + + ``was_on_time`` is recorded as True — a placeholder until the + on-time task computes it from ``now`` / ``today`` against the + instance due_date and optional due_time. ``today`` is accepted so + callers can thread the HA-local date through without a signature + change; it is unused here. + """ + instance_id = _validate_int_id(instance_id, "instance_id") + actor_source, actor_user_id, actor_child_id = _validate_actor( + actor_source, actor_user_id, actor_child_id + ) + instance = await QuestInstancesDao(database).get_by_id(instance_id) + if instance is None: + raise ValueError( + f"instance_id: quest instance {instance_id} does not exist" + ) + if await instance_state(database, instance_id) == "done": + return "done" + await append_event( + database, + instance.id, + instance.child_id, + EVENT_COMPLETED, + actor_source=actor_source, + actor_user_id=actor_user_id, + actor_child_id=actor_child_id, + was_on_time=True, + now=now, + ) + return "done" diff --git a/tests/test_completion.py b/tests/test_completion.py index 5412db5..b7272d7 100644 --- a/tests/test_completion.py +++ b/tests/test_completion.py @@ -8,7 +8,11 @@ import re import pytest -from custom_components.nestquest.completion import append_event, instance_state +from custom_components.nestquest.completion import ( + append_event, + complete_instance, + instance_state, +) from custom_components.nestquest.dao_children import ChildrenDao from custom_components.nestquest.dao_instances import ( EVENT_COMPLETED, @@ -333,7 +337,7 @@ def test_module_never_exposes_update_or_delete() -> None: ) assert "append_event" in public assert "instance_state" in public - assert "complete_instance" not in public + assert "complete_instance" in public assert "uncomplete_instance" not in public source = inspect.getsource(completion) assert "UPDATE" not in source @@ -444,3 +448,147 @@ def test_instance_state_three_events_returns_done_and_preserves_rows( assert len(after) == 3 _with_db(tmp_path, "state-three.db")(_body) + + +# --------------------------------------------------------------------------- +# complete_instance: append completed, no-op if already done +# --------------------------------------------------------------------------- + + +def test_complete_instance_appends_and_returns_done(tmp_path) -> None: + async def _body(database, child, instance): + events = CompletionEventsDao(database) + assert await events.list_by_instance(instance.id) == [] + state = await complete_instance( + database, + instance.id, + actor_source="user", + actor_user_id="user-1", + ) + assert state == "done" + assert await instance_state(database, instance.id) == "done" + rows = await events.list_by_instance(instance.id) + assert len(rows) == 1 + assert rows[0].event_type == EVENT_COMPLETED + assert rows[0].actor_source == "user" + assert rows[0].actor_user_id == "user-1" + assert rows[0].was_on_time is True + + _with_db(tmp_path, "complete-open.db")(_body) + + +def test_complete_instance_already_done_is_noop(tmp_path) -> None: + async def _body(database, child, instance): + first = await complete_instance( + database, + instance.id, + actor_source="user", + actor_user_id="user-1", + ) + events = CompletionEventsDao(database) + before = await events.list_by_instance(instance.id) + assert first == "done" + assert len(before) == 1 + second = await complete_instance( + database, + instance.id, + actor_source="user", + actor_user_id="user-2", + ) + after = await events.list_by_instance(instance.id) + assert second == "done" + assert after == before + assert after[0].actor_user_id == "user-1" + + _with_db(tmp_path, "complete-noop.db")(_body) + + +def test_complete_instance_unknown_instance_id_raises(tmp_path) -> None: + async def _body(database, child, instance): + with pytest.raises(ValueError, match="instance_id"): + await complete_instance( + database, + instance.id + 999, + actor_source="user", + actor_user_id="user-1", + ) + + _with_db(tmp_path, "complete-unknown.db")(_body) + + +def test_complete_instance_rejects_non_integer_id() -> None: + async def _body(): + with pytest.raises(ValueError, match="instance_id"): + await complete_instance( + object(), + "1", + actor_source="user", + actor_user_id="user-1", + ) + with pytest.raises(ValueError, match="instance_id"): + await complete_instance( + object(), + True, + actor_source="user", + actor_user_id="user-1", + ) + + _run(_body()) + + +def test_complete_instance_after_uncompleted_appends(tmp_path) -> None: + async def _body(database, child, instance): + await append_event( + database, + instance.id, + child.id, + EVENT_COMPLETED, + actor_source="user", + actor_user_id="user-1", + was_on_time=True, + ) + await append_event( + database, + instance.id, + child.id, + EVENT_UNCOMPLETED, + actor_source="user", + actor_user_id="user-1", + ) + events = CompletionEventsDao(database) + before = await events.list_by_instance(instance.id) + assert await instance_state(database, instance.id) == "open" + state = await complete_instance( + database, + instance.id, + actor_source="panel", + actor_child_id=child.id, + ) + assert state == "done" + after = await events.list_by_instance(instance.id) + assert len(after) == len(before) + 1 + assert after[-1].event_type == EVENT_COMPLETED + assert after[-1].actor_source == "panel" + assert after[-1].was_on_time is True + + _with_db(tmp_path, "complete-reopen.db")(_body) + + +def test_complete_instance_now_pins_occurred_at(tmp_path) -> None: + async def _body(database, child, instance): + pinned = datetime.datetime( + 2026, 9, 18, 8, 0, 0, tzinfo=datetime.timezone.utc + ) + await complete_instance( + database, + instance.id, + actor_source="user", + actor_user_id="user-1", + now=pinned, + ) + rows = await CompletionEventsDao(database).list_by_instance( + instance.id + ) + assert rows[0].occurred_at == "2026-09-18T08:00:00+00:00" + + _with_db(tmp_path, "complete-pinned.db")(_body)