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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codeplain
-Version: 0.3.11.dev17
+Version: 0.3.11.dev18
 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.dev18.dist-info}/RECORD

@@ -1,5 +1,5 @@
 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
@@ -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
@@ -96,6 +96,7 @@ tests/test_plainfile.py,sha256=wZ_PN4GULPWIpl_AK_r_6jkgtX0Ch8EHmN5IhX7huOE,11027
 tests/test_plainfileparser.py,sha256=M-7VDs0N79yqJOZRv55K12Kaz73oFz7Lqh3L_dqcpX4,25199
 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.dev18.dist-info/METADATA,sha256=zpMl6ZYhRFiw3yPqVZLyxFmFQkGagK6_kgmA8ELWkuI,7257
+codeplain-0.3.11.dev18.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+codeplain-0.3.11.dev18.dist-info/entry_points.txt,sha256=oDZkBqu9WhtZApb_K6ia8-fn9aojwmAsgnKELceX5T4,46
+codeplain-0.3.11.dev18.dist-info/licenses/LICENSE,sha256=pCeKgQ1mXE5OmNUuKOfOZh1T1vqkeCUxghE7N8qgnzc,11345
+codeplain-0.3.11.dev18.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,

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)

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()