codeplain 0.3.11.dev17__py3-none-any.whl → 0.3.11.dev19__py3-none-any.whl

{codeplain-0.3.11.dev17.dist-info → codeplain-0.3.11.dev19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeplain
-Version: 0.3.11.dev17
+Version: 0.3.11.dev19
 Summary: Transform plain language specifications into working code
 License-File: LICENSE
 Classifier: Environment :: Console

{codeplain-0.3.11.dev17.dist-info → codeplain-0.3.11.dev19.dist-info}/RECORD

@@ -1,10 +1,10 @@
 change_detection.py,sha256=CazORZrezeZSw2I6VBvieN-c2SEjieZPo6pNrKwmMVA,6915
-codeplain_REST_api.py,sha256=8JZu3HIvKG6d3qxs5tSM4Ll4tsMkGUHN4_VtKf6z-oA,21606
+codeplain_REST_api.py,sha256=ptb2u0mC5FJqMNeUbcc-bNXNhy9NRJZa5vI80uSFSwQ,22715
 concept_utils.py,sha256=TpyiQ4DfMtO231j-lPj65i0suRTPr8t9j3QNf9KiM4A,8080
 conformance_fix_journal.py,sha256=7wL3UOc3BWaUo5MCmiFbb3kIwOQ6iEpdQSyEmedo8Vk,9488
 diff_utils.py,sha256=AjiQlqo5pRos_8hVXZo5yBurl5BzSrTMGrQv4dCtRCg,1198
 event_bus.py,sha256=g5XLwRfjrvTIcB6urjREuCJzZj5TA93hy8lKXLGXuCE,650
-file_utils.py,sha256=MNZ5li1ofIMOYB6FCrMa_UkX6nkGCgSZuaqzhqVc1Ok,11682
+file_utils.py,sha256=IshKvld9LJLwXSB3lxZ1HQyVHa93I626BsTScBu95ss,12118
 git_preflight.py,sha256=vB2A8GyYz_iWr8jOE4POFLBHr3qihmedWuidspGdsrw,1509
 git_utils.py,sha256=gCUA6_9zg19f6k_0aVcRnIVlAJSBD0Vt6takx-0pKME,16547
 memory_management.py,sha256=CwIOQqF7Xo1sNfvP69zQRK_CpjinQD9dbolhRPl6lTk,2446
@@ -12,7 +12,7 @@ metadata_utils.py,sha256=YO17o7IAma5TT1ZN0pTwrLVr_KxFQ8APv02KqKPpI5k,1641
 module_renderer.py,sha256=IJBle8mbBARn_xrekjSpsVID7719yy2rNPkM15-ONoI,6982
 partial_rendering.py,sha256=uzZc2j4d3pAXzfiHw_y1TK4yLRsLOb1Mm21570AGxJ8,13837
 path_resolution.py,sha256=0tMqU0a1g4DYhTOp7QjLVSEkv_cgasb4NI1mK809dUM,2233
-plain2code.py,sha256=v8xBTv3mQjntpBTBJUvl5naGnSPFAzhEQTqpeRr40ow,18072
+plain2code.py,sha256=FV13ItuD9FQN4FhS4H7RXHh7MoQaAlGSh1ctkjeMSoo,20368
 plain2code_arguments.py,sha256=xMK-R13Vu005bHz3MUDY8F0Cf3ED9hCPqNsC6jGZmkk,17620
 plain2code_console.py,sha256=YGBONkQtwZUkrjxTKhqcBoRzW0EmSfYHPH8P4_FM60I,6040
 plain2code_events.py,sha256=rgDF5PDtNr_lEPvJmd1tIQXZrzwgzZW5b-_pykugqe4,1587
@@ -23,7 +23,7 @@ plain2code_read_config.py,sha256=D5CxnmTRjddupecWvstcUm0kIJWWzq5-Zmk6sU0wbIg,223
 plain2code_state.py,sha256=uePQlC29Pbhm1yXfdCFebONYdy6jo13gTTmXSwC11cQ,3168
 plain2code_telemetry.py,sha256=e4UCAoFklJMDWGQsL50i7nTLiOBy8gs86A0XO4WLgPo,4597
 plain2code_utils.py,sha256=unOxuqSQRpwG8YF6uoQhnZ3ZSTJRIUCPLdJ-1lRZR5M,1534
-plain_file.py,sha256=5UkjZNePMGmUhGqduwbm6R6DnT_rDX7q3gd8IzIDAF8,37092
+plain_file.py,sha256=yzdHYBZye1UjI6K-vcod5u9hPqQ_zBQS050yypdmB3M,37614
 plain_modules.py,sha256=nXlmw0J2rKkuU1Y3A68LVtZ1Ffdc-D5iMjxaXSaSHTQ,25963
 plain_spec.py,sha256=7nb5lLJKHZ3uu9THkSXyJ5brIKkbGW0ooVfRclLdlzA,16062
 system_config.py,sha256=sA8wiPmBMtRsLwSQ40U5pVdLazAafbV-1Z19Yp0HiSQ,5314
@@ -93,9 +93,10 @@ tests/test_plain2code_state.py,sha256=cowPZS9oRbv9J49CE4P3Rc47Q5oQOby4bTf2OlnRlB
 tests/test_plain2code_utils.py,sha256=-W8a7FquMJQ_pTdBoBF1XprzNL2G555QhdtXCy6BDyQ,1237
 tests/test_plain_modules.py,sha256=Fn3FeH-M4exnyFJDZzc9YWaLEfBmiqPH5TpiBT9jgAs,33033
 tests/test_plainfile.py,sha256=wZ_PN4GULPWIpl_AK_r_6jkgtX0Ch8EHmN5IhX7huOE,11027
-tests/test_plainfileparser.py,sha256=M-7VDs0N79yqJOZRv55K12Kaz73oFz7Lqh3L_dqcpX4,25199
+tests/test_plainfileparser.py,sha256=OY7dCilaUEeM4vAOShQYsZXKQzzUOi7nGYBaROu8Te8,26606
 tests/test_plainspec.py,sha256=ng55E8ajrH2-gPC1p_QDIe_zXplPvoqHJ-d57UWKFTw,3577
 tests/test_prepare_repositories_layout.py,sha256=PhJQLnHfjfjo6CTWoicyEKgL0_GtjwB2OKYAWSBVHtk,14638
+tests/test_render_finished_report.py,sha256=QtViWItlo8YB8bLOv3YwvfLprVZgZ9r8Q1Td7_vGi18,7445
 tests/test_requires.py,sha256=6tnHYaKudxN-RiQjSFoi9nHe_x0ze3QF-f-j67zAE74,1250
 tests/test_resolve_config_file.py,sha256=b87tDOvyzbsnE-QRWbZ97ou7NuyaAgskv-dbYBum31c,2830
 tests/test_script_path_resolution.py,sha256=tiEqMevQRXr9YpfHN0xldOOQpLAUgnSqTzeZWkKHaUY,4156
@@ -116,8 +117,8 @@ tui/spinner.py,sha256=Ro6Gd9Przf-whuHqPRY6HwI0T57yJjyNPbhDbigZKZE,2471
 tui/state_handlers.py,sha256=zbUS_D9eU8qIwVpaxPEp9zL9bpg8gXsWNoUaqg9TLrQ,16664
 tui/styles.css,sha256=kiC7Og_2G1E7owoiZgV95-3_dSeQnsNj3qzaY04xkDg,6727
 tui/widget_helpers.py,sha256=jitm2WHiKj-NVFL-hULxWzckPreRbUTl9OIZLN31-ek,6997
-codeplain-0.3.11.dev17.dist-info/METADATA,sha256=II9TqLOmkx5BY2vKCDWHG-ibzpQ0we6NPkrJnKjoFmM,7257
-codeplain-0.3.11.dev17.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-codeplain-0.3.11.dev17.dist-info/entry_points.txt,sha256=oDZkBqu9WhtZApb_K6ia8-fn9aojwmAsgnKELceX5T4,46
-codeplain-0.3.11.dev17.dist-info/licenses/LICENSE,sha256=pCeKgQ1mXE5OmNUuKOfOZh1T1vqkeCUxghE7N8qgnzc,11345
-codeplain-0.3.11.dev17.dist-info/RECORD,,
+codeplain-0.3.11.dev19.dist-info/METADATA,sha256=hh5z_WBJjGHeYBl89nFPmHXI5Ed51lYqAb_-SutUCX8,7257
+codeplain-0.3.11.dev19.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+codeplain-0.3.11.dev19.dist-info/entry_points.txt,sha256=oDZkBqu9WhtZApb_K6ia8-fn9aojwmAsgnKELceX5T4,46
+codeplain-0.3.11.dev19.dist-info/licenses/LICENSE,sha256=pCeKgQ1mXE5OmNUuKOfOZh1T1vqkeCUxghE7N8qgnzc,11345
+codeplain-0.3.11.dev19.dist-info/RECORD,,

codeplain_REST_api.py

@@ -11,6 +11,10 @@ from plain2code_state import RunState
 MAX_RETRIES = 4
 RETRY_DELAY = 3
 
+# A report the render does not consume must not be able to hold the process open
+# at exit, and requests waits indefinitely by default.
+REPORT_TIMEOUT_SECONDS = 5
+
 RETRY_ERROR_CODES = [
     "LLMInternalError",
 ]
@@ -125,6 +129,7 @@ class CodeplainAPI:
         run_state: Optional[RunState],
         num_retries: int = MAX_RETRIES,
         silent: bool = False,
+        timeout: Optional[int] = None,
     ):
         if run_state is not None:
             self._extend_payload_with_run_state(payload, run_state)
@@ -134,7 +139,7 @@ class CodeplainAPI:
 
         for attempt in range(num_retries + 1):
             try:
-                response = requests.post(endpoint_url, headers=headers, json=payload)
+                response = requests.post(endpoint_url, headers=headers, json=payload, timeout=timeout)
 
                 try:
                     response_json = response.json()
@@ -173,6 +178,27 @@ class CodeplainAPI:
         }
         return self.post_request(endpoint_url, headers, payload, None, num_retries=0, silent=True)
 
+    def render_finished(self, outcome: str, run_state: RunState):
+        """Report the terminal state a render reached.
+
+        Called once per render, whatever the outcome. The render state machine
+        lives here, so the API cannot tell a finished render from one still
+        going; it has to be told.
+
+        No retries and no console output: a report has no result the render
+        needs, and must not add minutes to a render that has already ended nor
+        print retry noise over the exit summary.
+        """
+        endpoint_url = f"{self.api_url}/render_finished"
+        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}
+        payload = {
+            "outcome": outcome,
+        }
+
+        return self.post_request(
+            endpoint_url, headers, payload, run_state, num_retries=0, silent=True, timeout=REPORT_TIMEOUT_SECONDS
+        )
+
     def render_functional_requirement(
         self,
         frid: str,

file_utils.py

@@ -180,6 +180,20 @@ def open_from(dirs, file_name):
     return None
 
 
+def resolve_linked_resource(dirs, file_name):
+    """Return the first existing path for file_name across dirs, or None if not found.
+
+    Mirrors the search order used by open_from so that validating a linked resource and
+    loading it can never disagree.
+    """
+    for dir in dirs:
+        full_file_name = os.path.join(dir, file_name)
+        if os.path.exists(full_file_name):
+            return full_file_name
+
+    return None
+
+
 def load_linked_resources(template_dirs: list[str], resources_list, module_name: str):
     linked_resources = {}
 

plain2code.py

@@ -61,6 +61,11 @@ from tui.plain_module_render_choice_tui import PlainModuleRenderChoiceTUI
 DEFAULT_TEMPLATE_DIRS = "standard_template_library"
 RENDER_THREAD_SHUTDOWN_TIMEOUT = 0.7
 
+# The terminal states a render can reach, as the API names them.
+RENDER_OUTCOME_COMPLETED = "completed"
+RENDER_OUTCOME_FAILED = "failed"
+RENDER_OUTCOME_CANCELLED = "cancelled"
+
 # Exceptions that represent expected, user-facing error conditions. They are
 # reported to the user directly and must never be sent to Sentry as crashes.
 EXPECTED_EXCEPTIONS = (
@@ -177,6 +182,52 @@ def _check_connection(codeplainAPI: codeplain_api.CodeplainAPI) -> Optional[str]
     return response.get("user_email")
 
 
+def _render_outcome(run_state: RunState, interrupted: bool = False) -> str:
+    """Name the terminal state a render reached.
+
+    Ctrl-C is the user stopping the render, so it is a cancellation. It does not
+    set render_cancelled: the exit summary reads that flag, and its wording for
+    an interrupt stays as it is.
+
+    Cancellation is tested first. A cancelled render leaves render_succeeded
+    False, so asking about success first would report it as a failure.
+    """
+    if interrupted or run_state.render_cancelled:
+        return RENDER_OUTCOME_CANCELLED
+    if run_state.render_succeeded:
+        return RENDER_OUTCOME_COMPLETED
+    return RENDER_OUTCOME_FAILED
+
+
+def report_render_finished(
+    codeplainAPI: codeplain_api.CodeplainAPI, run_state: RunState, interrupted: bool = False
+) -> None:
+    """Tell the API which terminal state this render reached.
+
+    The API cannot work it out for itself - the state machine lives here - and
+    main()'s finally is the one place that sees every ending: success, failure,
+    cancellation, an unexpected crash and a keyboard interrupt alike. The state
+    machine's own completed and failed hooks see only two of the five.
+
+    Reported only once the connection check has set a user email, which is
+    exactly the condition "the API knows who we are". A missing key, an invalid
+    key and an outdated client all leave it unset, and none of them got as far
+    as a render.
+
+    Never raises. A report must not change the exit code, and must not mask the
+    error that ended the render.
+    """
+    if not run_state.user_email:
+        return
+
+    try:
+        codeplainAPI.render_finished(_render_outcome(run_state, interrupted), run_state)
+    except Exception:
+        # Deliberately silent: logging has stopped by now, and a failed report
+        # is not the user's problem.
+        pass
+
+
 def warn_if_acceptance_tests_without_conformance_script(plain_module, args) -> None:
     """Warn when any loaded module (including required modules) defines acceptance tests
     but no conformance tests script is configured.
@@ -214,6 +265,7 @@ def validate_linked_resources(plain_module) -> None:
 
 def render(  # noqa: C901
     plain_module: plain_modules.PlainModule,
+    codeplainAPI: codeplain_api.CodeplainAPI,
     args,
     run_state: RunState,
     event_bus: EventBus,
@@ -224,10 +276,6 @@ def render(  # noqa: C901
     if args.render_range or args.render_from:
         render_range = plain_spec.compute_render_range(args, plain_module.plain_source)
 
-    codeplainAPI = codeplain_api.CodeplainAPI(args.api_key, console)
-    assert args.api is not None and args.api != "", "API URL is required"
-    codeplainAPI.api_url = args.api
-
     run_state.user_email = _check_connection(codeplainAPI)
 
     stop_event = threading.Event()
@@ -419,6 +467,10 @@ def main():  # noqa: C901
     if not args.api:
         args.api = system_config.default_api_url
 
+    assert args.api is not None and args.api != "", "API URL is required"
+    codeplainAPI = codeplain_api.CodeplainAPI(args.api_key, console)
+    codeplainAPI.api_url = args.api
+
     run_state = RunState(spec_filename=args.filename, replay_with=args.replay_with)
 
     if args.headless:
@@ -431,6 +483,7 @@ def main():  # noqa: C901
 
     exc_info = None
     error_message = None
+    interrupted = False
 
     try:
         # Validate API key is present
@@ -438,10 +491,11 @@ def main():  # noqa: C901
             raise MissingAPIKey(
                 "Your API key is required. Please set the CODEPLAIN_API_KEY environment variable or provide it with the --api-key argument.\n"
             )
-        render(plain_module, args, run_state, event_bus, default_log_level)
+        render(plain_module, codeplainAPI, args, run_state, event_bus, default_log_level)
     except BaseException as e:
         if isinstance(e, KeyboardInterrupt):
             error_message = "Keyboard interrupt"
+            interrupted = True
         else:
             error_message = str(e) if str(e) else repr(e)
 
@@ -460,6 +514,8 @@ def main():  # noqa: C901
         # Remove any scratch extractions created for archive-only ("<module>.module") modules.
         for module in plain_module.all_required_modules + [plain_module]:
             module.cleanup_scratch()
+        # Last, so nothing the user is waiting for sits behind a network call.
+        report_render_finished(codeplainAPI, run_state, interrupted)
 
     if args.headless and (exc_info is not None or not run_state.render_succeeded):
         sys.exit(1)

plain_file.py

@@ -90,7 +90,7 @@ def remove_quotes(token):
     token.children = tuple(new_children)
 
 
-def check_section_for_linked_resources(section):
+def check_section_for_linked_resources(section, template_dirs):
     linked_resources = []
     for link in traverse(section, klass=Link):
         parsed_url = urlparse(link.node.target)
@@ -99,11 +99,19 @@ def check_section_for_linked_resources(section):
                 f"Plain syntax error: Only relative links are allowed (text: {link.node.children[0].content}, target: {link.node.target})."
             )
 
-        if not os.path.exists(link.node.target):
-            raise PlainSyntaxError(f"Plain syntax error: Link {link.node.target} does not exist.")
+        resolved_target = file_utils.resolve_linked_resource(template_dirs, link.node.target)
+        if resolved_target is None:
+            searched_dirs = "\n".join(f"  {position}. {dir}" for position, dir in enumerate(template_dirs, start=1))
+            raise PlainSyntaxError(
+                f"Plain syntax error: Link {link.node.target} does not exist. "
+                f"Linked resources are looked up relative to the following directories "
+                f"(highest to lowest precedence):\n{searched_dirs}"
+            )
 
-        if not os.path.isfile(link.node.target):
-            raise PlainSyntaxError(f"Plain syntax error: Link {link.node.target} must be a file.")
+        if not os.path.isfile(resolved_target):
+            raise PlainSyntaxError(
+                f"Plain syntax error: Link {link.node.target} must be a file (resolved to {resolved_target})."
+            )
 
         if len(link.node.children) != 1:
             raise PlainSyntaxError(f"Plain syntax error: Link must have text specified (link: {link.node.target}).")
@@ -122,15 +130,15 @@ def check_section_for_linked_resources(section):
         section.linked_resources = linked_resources
 
 
-def check_for_linked_resources(plain_source):
+def check_for_linked_resources(plain_source, template_dirs):
     for specification_heading in plain_spec.ALLOWED_SPECIFICATION_HEADINGS:
         if specification_heading in plain_source and hasattr(plain_source[specification_heading], "children"):
             for requirement in plain_source[specification_heading].children:
-                check_section_for_linked_resources(requirement)
+                check_section_for_linked_resources(requirement, template_dirs)
 
                 if hasattr(requirement, plain_spec.ACCEPTANCE_TESTS):
                     for acceptance_test in requirement.acceptance_tests:
-                        check_section_for_linked_resources(acceptance_test)
+                        check_section_for_linked_resources(acceptance_test, template_dirs)
 
 
 def process_section_code_variables(section, code_variables):
@@ -845,7 +853,7 @@ def plain_file_parser(  # noqa: C901
 
     process_acceptance_tests(plain_file_parse_result.plain_source)
 
-    check_for_linked_resources(plain_file_parse_result.plain_source)
+    check_for_linked_resources(plain_file_parse_result.plain_source, template_dirs)
 
     marshalled_plain_source = marshall_plain_source(plain_file_parse_result.plain_source)
 

tests/test_plainfileparser.py

@@ -146,14 +146,30 @@ def test_invalid_absolute_link(get_test_data_path):
         )
 
 
+def test_missing_link_error_lists_searched_directories(get_test_data_path):
+    """The error tells the user which directories were searched for the linked resource."""
+    plain_file_dir = get_test_data_path("data/plainfile")
+
+    with pytest.raises(PlainSyntaxError) as exception_info:
+        plain_file.plain_file_parser(
+            "plain_source_with_missing_link.plain",
+            [plain_file_dir],
+        )
+
+    message = str(exception_info.value)
+    assert "resources/missing_resource.yaml does not exist" in message
+    assert "highest to lowest precedence" in message
+    assert plain_file_dir in message
+
+
 def test_reference_link_parsing(get_test_data_path):
     _, plain_sections, _ = plain_file.plain_file_parser(
         "task_manager_with_reference_links.plain",
         [get_test_data_path("data/plainfile")],
     )
     asserted_resources = [
-        "tests/data/plainfile/task_list_ui_specification.yaml",
-        "tests/data/plainfile/add_new_task_modal_specification.yaml",
+        "task_list_ui_specification.yaml",
+        "add_new_task_modal_specification.yaml",
     ]
     for functional_requirement in plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS]:
         if "linked_resources" not in functional_requirement:
@@ -180,13 +196,36 @@ def test_reference_link_parsing(get_test_data_path):
     assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][1]["linked_resources"] == [
         {
             "text": "task_list_ui_specification.yaml",
-            "target": "tests/data/plainfile/task_list_ui_specification.yaml",
+            "target": "task_list_ui_specification.yaml",
+        }
+    ]
+    assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][2]["linked_resources"] == [
+        {
+            "text": "add_new_task_modal_specification.yaml",
+            "target": "add_new_task_modal_specification.yaml",
+        }
+    ]
+
+
+def test_reference_link_parsing_independent_of_working_directory(get_test_data_path, monkeypatch, tmp_path):
+    """Linked resources resolve against the plain file's directory, not the invocation cwd."""
+    monkeypatch.chdir(tmp_path)
+
+    _, plain_sections, _ = plain_file.plain_file_parser(
+        "task_manager_with_reference_links.plain",
+        [get_test_data_path("data/plainfile")],
+    )
+
+    assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][1]["linked_resources"] == [
+        {
+            "text": "task_list_ui_specification.yaml",
+            "target": "task_list_ui_specification.yaml",
         }
     ]
     assert plain_sections[plain_spec.FUNCTIONAL_REQUIREMENTS][2]["linked_resources"] == [
         {
             "text": "add_new_task_modal_specification.yaml",
-            "target": "tests/data/plainfile/add_new_task_modal_specification.yaml",
+            "target": "add_new_task_modal_specification.yaml",
         }
     ]
 

tests/test_render_finished_report.py

@@ -0,0 +1,200 @@
+"""Tests for reporting a render's terminal state to the API.
+
+The render state machine lives in the client, so the API only learns how a
+render ended because main() tells it. Two things are worth proving: that the
+outcome names the right ending, and that main() reports on every path out -
+including the ones the state machine never sees, like a keyboard interrupt.
+"""
+
+from argparse import Namespace
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import plain2code
+from plain2code_exceptions import InvalidAPIKey
+from plain2code_state import RunState
+
+
+def make_run_state(succeeded=False, cancelled=False, user_email="user@codeplain.ai"):
+    run_state = RunState(spec_filename="project.plain")
+    run_state.set_render_succeeded(succeeded)
+    if cancelled:
+        run_state.set_render_cancelled()
+    run_state.user_email = user_email
+    return run_state
+
+
+class TestRenderOutcome:
+    def test_a_successful_render_is_completed(self):
+        assert plain2code._render_outcome(make_run_state(succeeded=True)) == "completed"
+
+    def test_an_unsuccessful_render_is_failed(self):
+        assert plain2code._render_outcome(make_run_state(succeeded=False)) == "failed"
+
+    def test_a_cancelled_render_is_cancelled(self):
+        """A cancelled render leaves render_succeeded False, so cancellation has to
+        be asked about first or it would be reported as a failure."""
+        assert plain2code._render_outcome(make_run_state(cancelled=True)) == "cancelled"
+
+    def test_cancellation_wins_over_a_success_already_recorded(self):
+        """Cancelling during the dist step leaves both flags set."""
+        assert plain2code._render_outcome(make_run_state(succeeded=True, cancelled=True)) == "cancelled"
+
+    def test_an_interrupted_render_is_cancelled(self):
+        """Ctrl-C is the user stopping the render. It does not set the cancelled
+        flag, so the outcome has to be told about it."""
+        assert plain2code._render_outcome(make_run_state(), interrupted=True) == "cancelled"
+
+
+class TestReportRenderFinished:
+    def test_reports_the_outcome_with_the_render_state(self):
+        api = MagicMock()
+        run_state = make_run_state(succeeded=True)
+
+        plain2code.report_render_finished(api, run_state)
+
+        api.render_finished.assert_called_once_with("completed", run_state)
+
+    def test_says_nothing_when_the_api_never_identified_us(self):
+        """user_email is set by the connection check, so an absent one means a
+        missing key, an invalid key or an outdated client - none of which rendered."""
+        api = MagicMock()
+
+        plain2code.report_render_finished(api, make_run_state(user_email=None))
+
+        api.render_finished.assert_not_called()
+
+    @pytest.mark.parametrize(
+        "failure",
+        [
+            ConnectionError("api unreachable"),
+            TimeoutError("api slow"),
+            RuntimeError("something else entirely"),
+        ],
+    )
+    def test_a_failed_report_never_propagates(self, failure):
+        """The report is the last thing a render does. It must not become the
+        reason the render looks like it failed."""
+        api = MagicMock()
+        api.render_finished.side_effect = failure
+
+        plain2code.report_render_finished(api, make_run_state(succeeded=True))
+
+
+def make_args(api_key="test-key", headless=False):
+    return Namespace(
+        version=False,
+        status=False,
+        full_plain=False,
+        dry_run=False,
+        api_key=api_key,
+        api="https://api.example.com",
+        filename="project.plain",
+        template_dir=None,
+        build_folder="build",
+        render_range=None,
+        render_from=None,
+        headless=headless,
+        replay_with=None,
+        log_to_file=False,
+        log_file_name="codeplain.log",
+        conformance_tests_script=None,
+        unittests_script=None,
+        prepare_environment_script=None,
+    )
+
+
+def run_main(render_side_effect=None, api_key="test-key"):
+    """Drive main() with everything but the reporting path stubbed out.
+
+    render() is replaced, so the stub is what decides how the render "ended" -
+    which is the point: the report must be made from main()'s finally whatever
+    render did, not from inside the state machine.
+
+    Returns the API client mock so the caller can inspect the report.
+    """
+    api = MagicMock()
+
+    def fake_render(plain_module, codeplainAPI, args, run_state, event_bus, default_log_level="INFO"):
+        run_state.user_email = "user@codeplain.ai"
+        if render_side_effect is not None:
+            render_side_effect(run_state)
+
+    with (
+        patch("plain2code.parse_arguments", return_value=make_args(api_key=api_key)),
+        patch("plain2code.file_utils.get_template_directories", return_value=["templates"]),
+        patch("plain2code.plain_modules.PlainModule", return_value=MagicMock(all_required_modules=[])),
+        patch("plain2code.setup_logging", return_value="INFO"),
+        patch("plain2code.initialize_telemetry"),
+        patch("plain2code.stop_narrating"),
+        patch("plain2code.print_exit_summary"),
+        patch("plain2code.dump_crash_logs"),
+        patch("plain2code.capture_crash"),
+        patch("plain2code.codeplain_api.CodeplainAPI", return_value=api),
+        patch("plain2code.render", side_effect=fake_render),
+    ):
+        plain2code.main()
+
+    return api
+
+
+class TestMainReportsEveryEnding:
+    """main()'s finally is the only place that sees all of these."""
+
+    def test_a_completed_render_is_reported(self):
+        api = run_main(lambda run_state: run_state.set_render_succeeded(True))
+
+        assert api.render_finished.call_args.args[0] == "completed"
+
+    def test_a_failed_render_is_reported(self):
+        def fail(run_state):
+            run_state.set_render_succeeded(False)
+            raise Exception("rendering blew up")
+
+        api = run_main(fail)
+
+        assert api.render_finished.call_args.args[0] == "failed"
+
+    def test_an_expected_error_is_reported_as_a_failure(self):
+        def fail(run_state):
+            raise InvalidAPIKey("key went stale mid-render")
+
+        api = run_main(fail)
+
+        assert api.render_finished.call_args.args[0] == "failed"
+
+    def test_a_cancelled_render_is_reported(self):
+        api = run_main(lambda run_state: run_state.set_render_cancelled())
+
+        assert api.render_finished.call_args.args[0] == "cancelled"
+
+    def test_a_keyboard_interrupt_is_reported_as_cancelled(self):
+        """Ctrl-C never enters a terminal state in the state machine, so this
+        ending exists only in main(). In headless mode it is the only way to stop
+        a render, and stopping is a cancellation, not a failure."""
+
+        def interrupt(run_state):
+            raise KeyboardInterrupt()
+
+        api = run_main(interrupt)
+
+        assert api.render_finished.call_args.args[0] == "cancelled"
+
+    def test_a_keyboard_interrupt_leaves_the_exit_summary_alone(self):
+        """The summary reads render_cancelled. Only the reported outcome changes."""
+        captured = {}
+
+        def interrupt(run_state):
+            captured["run_state"] = run_state
+            raise KeyboardInterrupt()
+
+        run_main(interrupt)
+
+        assert captured["run_state"].render_cancelled is False
+
+    def test_a_missing_api_key_reports_nothing(self):
+        """render() is never reached, so nothing identified the caller."""
+        api = run_main(api_key=None)
+
+        api.render_finished.assert_not_called()