codeplain 0.3.9__py3-none-any.whl → 0.3.10.dev2__py3-none-any.whl

tests/test_headless_logging.py

@@ -0,0 +1,177 @@
+"""Tests for what a headless render says while it is running.
+
+Headless suppresses Rich output and attaches no TUI handler, so before this the only
+sink was the log file — the process was silent on stdout for its entire run and a
+CI job could not tell a render wedged for hours from a healthy one until the file was
+collected at the end. One four-hour render produced 858 lines, all of them in its first
+two minutes.
+
+The second half of this file guards the hazard that adding a second handler exposes:
+one record is handed to every handler in turn, so a formatter that rewrites
+`record.msg` in place corrupts the output of the handlers after it.
+"""
+
+import logging
+import sys
+from unittest.mock import MagicMock
+
+import pytest
+
+from plain2code import setup_logging
+from plain2code_console import console
+from plain2code_logger import (
+    LOGGER_NAME,
+    ElapsedTimeFormatter,
+    IndentedFormatter,
+    stop_narrating,
+)
+
+
+@pytest.fixture
+def run_state():
+    state = MagicMock()
+    state.get_live_render_time.return_value = 3661  # 01:01:01
+    return state
+
+
+def record(message, args=None):
+    return logging.LogRecord(
+        name="codeplain",
+        level=logging.INFO,
+        pathname=__file__,
+        lineno=1,
+        msg=message,
+        args=args,
+        exc_info=None,
+    )
+
+
+def test_the_elapsed_formatter_stamps_the_render_time(run_state):
+    assert ElapsedTimeFormatter(run_state).format(record("hello")) == "[01:01:01] INFO codeplain: hello"
+
+
+def test_continuation_lines_are_indented_past_the_timestamp(run_state):
+    formatted = ElapsedTimeFormatter(run_state).format(record("first\nsecond"))
+
+    assert formatted == "[01:01:01] INFO codeplain: first\n           second"
+
+
+def test_formatting_twice_does_not_indent_twice(run_state):
+    """Two handlers share one record. Formatting must be idempotent from the record's
+    point of view, or the file log inherits the stdout log's indentation."""
+    formatter = ElapsedTimeFormatter(run_state)
+    entry = record("first\nsecond")
+
+    first_pass = formatter.format(entry)
+    second_pass = formatter.format(entry)
+
+    assert first_pass == second_pass
+
+
+def test_two_different_formatters_do_not_corrupt_each_other(run_state):
+    """The real pairing in a headless render that also logs to a file."""
+    entry = record("first\nsecond")
+
+    IndentedFormatter("%(levelname)s:%(name)s:%(message)s").format(entry)
+    elapsed = ElapsedTimeFormatter(run_state).format(entry)
+
+    assert elapsed == "[01:01:01] INFO codeplain: first\n           second"
+
+
+def test_the_indented_formatter_leaves_the_record_alone(run_state):
+    entry = record("first\nsecond")
+
+    IndentedFormatter("%(levelname)s:%(name)s:%(message)s").format(entry)
+
+    assert entry.msg == "first\nsecond"
+
+
+def test_arguments_are_interpolated_exactly_once(run_state):
+    """The copy carries an already-interpolated message, so its args must be cleared —
+    otherwise the parent formatter interpolates a second time and raises."""
+    assert ElapsedTimeFormatter(run_state).format(record("value is %s", ("x",))).endswith("value is x")
+
+
+@pytest.fixture
+def configured_handlers(run_state):
+    """setup_logging mutates the process-wide "codeplain" logger; restore it after."""
+    logger = logging.getLogger(LOGGER_NAME)
+    saved_handlers, saved_level = list(logger.handlers), logger.level
+
+    def configure(headless):
+        logger.handlers = []
+        args = MagicMock()
+        args.verbose = False
+        args.logging_config_path = None
+        setup_logging(args, MagicMock(), run_state, log_to_file=False, log_file_path="", headless=headless)
+        return logger.handlers
+
+    yield configure
+
+    logger.handlers, logger.level = saved_handlers, saved_level
+
+
+def stdout_handlers(handlers):
+    return [h for h in handlers if type(h) is logging.StreamHandler and h.stream is sys.stdout]
+
+
+def test_a_headless_render_narrates_to_stdout(configured_handlers):
+    assert len(stdout_handlers(configured_handlers(headless=True))) == 1
+
+
+def test_the_stdout_handler_carries_the_elapsed_time_format(configured_handlers):
+    """It has to be readable as a render log, not just present."""
+    handler = stdout_handlers(configured_handlers(headless=True))[0]
+
+    assert isinstance(handler.formatter, ElapsedTimeFormatter)
+
+
+def test_an_interactive_render_does_not_duplicate_output_on_stdout(configured_handlers):
+    """The TUI already draws the log; a second copy on stdout would fight it for the
+    terminal."""
+    assert stdout_handlers(configured_handlers(headless=False)) == []
+
+
+def test_the_formatter_survives_a_run_state_that_cannot_report_time():
+    """A record can be logged before the render clock exists; it must still be readable."""
+    broken = MagicMock()
+    broken.get_live_render_time.side_effect = RuntimeError("no clock yet")
+
+    assert ElapsedTimeFormatter(broken).format(record("hello")) == "[00:00:00] INFO codeplain: hello"
+
+
+@pytest.fixture
+def quiet_console():
+    """Headless suppresses Rich output, so stdout carries the log sink and nothing else."""
+    saved, console.quiet = console.quiet, True
+    yield
+    console.quiet = saved
+
+
+def test_specification_text_reaches_the_stdout_sink(configured_handlers, quiet_console, capsys):
+    """The narration carries the functional requirement, like every other record.
+
+    These logs are the user's own, on the user's own machine, and the specification is
+    theirs. Withholding it here buys nothing and costs them the detail that says which
+    requirement a wedged render is stuck on. The rule this sink was briefly written
+    against is about what *we* retain - see the Sentry and analytics scrubbers, which
+    keep specification text out of anything leaving the machine."""
+    configured_handlers(headless=True)
+
+    console.info("Rendering functionality 3: the user's whole functional requirement")
+    console.info("Running unit tests.")
+
+    printed = capsys.readouterr().out
+    assert "whole functional requirement" in printed
+    assert "Running unit tests." in printed
+
+
+def test_narration_stops_before_the_exit_summary(configured_handlers, quiet_console, capsys):
+    """The summary bypasses logging, so a still-attached sink reports a failure twice."""
+    configured_handlers(headless=True)
+    capsys.readouterr()
+
+    stop_narrating()
+    console.info("this arrives after the render is over")
+
+    assert "after the render is over" not in capsys.readouterr().out

tests/test_plain_modules.py

@@ -7,14 +7,16 @@ These tests build real ``PlainModule`` instances from fixtures in
 
 import json
 import os
+import shutil
 import tempfile
+import zipfile
 from pathlib import Path
 
 import pytest
 
 from change_detection import determine_partial_render_start
 from git_utils import FUNCTIONAL_REQUIREMENT_FINISHED_COMMIT_MESSAGE, add_all_files_and_commit, init_git_repo
-from plain2code_exceptions import ModuleDoesNotExistError
+from plain2code_exceptions import InvalidModuleArchiveError, ModuleDoesNotExistError
 from plain_modules import MODULE_METADATA_FILENAME, PlainModule
 
 # --------------------------------------------------------------------------
@@ -361,6 +363,270 @@ def test_wipe_module_removes_whole_module_folder(solo_module):
     assert not os.path.exists(solo_module.module_folder)
 
 
+# --------------------------------------------------------------------------
+# Zipped modules (<module>.module archives)
+# --------------------------------------------------------------------------
+
+
+def _init_repo_with_finished_frid(repo_path: str, module_name: str, frid: str) -> None:
+    """Init a git repo at ``repo_path`` and commit a FUNCTIONAL_REQUIREMENT_FINISHED checkpoint."""
+    os.makedirs(repo_path, exist_ok=True)
+    init_git_repo(repo_path, module_name=module_name)
+    marker = Path(repo_path) / f"frid_{frid}.txt"
+    marker.write_text(f"frid {frid}\n")
+    add_all_files_and_commit(
+        repo_path,
+        FUNCTIONAL_REQUIREMENT_FINISHED_COMMIT_MESSAGE.format(frid),
+        module_name=module_name,
+        frid=frid,
+    )
+
+
+def _setup_full_module(module: PlainModule, frid: str = "1") -> None:
+    """Create a realistic on-disk module: code/ and tests/ git repos plus metadata."""
+    _init_repo_with_finished_frid(module.module_build_folder, module.module_name, frid)
+    _init_repo_with_finished_frid(module.module_conformance_tests_folder, module.module_name, frid)
+    _write_metadata(module, {"source_hash": "seed", "functionalities": ["fr1"]})
+
+
+def _zip_module_flat(module_folder: str, archive_path: str) -> None:
+    """Zip the *contents* of ``module_folder`` (code/, tests/, .codeplain/ at the archive
+    root, including .git) into ``archive_path``."""
+    with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for root, _dirs, files in os.walk(module_folder):
+            for name in files:
+                full = os.path.join(root, name)
+                zf.write(full, os.path.relpath(full, module_folder))
+
+
+def _archive_module(module: PlainModule) -> str:
+    """Turn an on-disk module into an archive-only module: zip it, then remove the folder."""
+    archive_path = module.module_archive_path
+    _zip_module_flat(module.module_folder, archive_path)
+    shutil.rmtree(module.module_folder)
+    return archive_path
+
+
+def test_folder_takes_precedence_over_archive(solo_module):
+    """When both the folder and the archive exist, the folder is used and the archive untouched."""
+    _setup_full_module(solo_module)
+    # Create a stray archive alongside the real folder.
+    with zipfile.ZipFile(solo_module.module_archive_path, "w") as zf:
+        zf.writestr("code/marker.txt", "x")
+
+    default = solo_module._default_module_folder
+    solo_module.materialize()
+
+    assert solo_module.module_folder == default
+    assert solo_module.module_build_folder == os.path.join(default, "code")
+    assert os.path.isfile(solo_module.module_archive_path)  # untouched
+
+
+def test_materialize_resolves_paths_to_scratch(solo_module):
+    _setup_full_module(solo_module)
+    default = solo_module._default_module_folder
+    _archive_module(solo_module)
+
+    assert solo_module.is_archived_only()
+    solo_module.materialize()
+
+    # Paths now resolve into a scratch extraction, not the real (absent) folder.
+    assert solo_module.module_folder != default
+    assert not os.path.exists(default)  # real folder NOT created
+    assert os.path.isfile(solo_module.module_archive_path)  # archive preserved
+    assert os.path.isdir(os.path.join(solo_module.module_build_folder, ".git"))
+    assert os.path.isdir(os.path.join(solo_module.module_conformance_tests_folder, ".git"))
+    # Git-backed reads work against the scratch tree.
+    name, frid = solo_module.get_module_render_status()
+    assert name == solo_module.module_name
+    assert frid == "1"
+
+    solo_module.cleanup_scratch()
+    assert solo_module.module_folder == default  # resolution reset
+
+
+def test_get_repo_none_before_materialize_and_present_after(solo_module):
+    """Guards the skip-detection bug: an archive-only module reads as "no repo" until materialized,
+    so the orchestrator's `get_repo() is not None` check only passes after materialize()."""
+    _setup_full_module(solo_module)
+    _archive_module(solo_module)
+
+    assert solo_module.get_repo() is None  # would wrongly force a re-render if consumed as-is
+    solo_module.materialize()
+    assert solo_module.get_repo() is not None  # now recognised as already rendered
+
+    solo_module.cleanup_scratch()
+
+
+def test_materialize_is_idempotent(solo_module):
+    _setup_full_module(solo_module)
+    _archive_module(solo_module)
+    solo_module.materialize()
+    first = solo_module.module_folder
+    solo_module.materialize()
+    assert solo_module.module_folder == first
+    solo_module.cleanup_scratch()
+
+
+def test_ensure_module_unpacked_from_archive(solo_module):
+    _setup_full_module(solo_module)
+    default = solo_module._default_module_folder
+    _archive_module(solo_module)
+
+    solo_module.ensure_module_unpacked()
+
+    assert solo_module.module_folder == default
+    assert os.path.isdir(os.path.join(default, "code", ".git"))
+    assert os.path.isdir(os.path.join(default, "tests", ".git"))
+    assert not os.path.exists(solo_module.module_archive_path)  # archive removed
+    # Idempotent: a second call is a no-op.
+    solo_module.ensure_module_unpacked()
+    assert os.path.isdir(default)
+
+
+def test_ensure_module_unpacked_after_materialize(solo_module):
+    """materialize() then ensure_module_unpacked() lands content in the real folder."""
+    _setup_full_module(solo_module)
+    default = solo_module._default_module_folder
+    _archive_module(solo_module)
+
+    solo_module.materialize()
+    solo_module.ensure_module_unpacked()
+
+    assert solo_module.module_folder == default
+    assert os.path.isdir(os.path.join(default, "code", ".git"))
+    assert not os.path.exists(solo_module.module_archive_path)
+
+
+def test_ensure_module_unpacked_noop_when_folder_exists(solo_module):
+    """A stray archive next to an existing folder is removed; the folder is kept."""
+    _setup_full_module(solo_module)
+    with zipfile.ZipFile(solo_module.module_archive_path, "w") as zf:
+        zf.writestr("code/marker.txt", "x")
+
+    solo_module.ensure_module_unpacked()
+
+    assert os.path.isdir(solo_module.module_build_folder)
+    assert not os.path.exists(solo_module.module_archive_path)
+
+
+def test_wipe_module_removes_archive_and_scratch(solo_module):
+    _setup_full_module(solo_module)
+    _archive_module(solo_module)
+    solo_module.materialize()
+    scratch = solo_module._scratch_dir
+
+    solo_module.wipe_module()
+
+    assert not os.path.exists(solo_module.module_archive_path)
+    assert scratch is not None and not os.path.exists(scratch)
+    assert solo_module.module_folder == solo_module._default_module_folder
+
+
+def test_render_status_parity_folder_vs_archive(fixtures_dir, tmp_build_folder):
+    """The same module (same logical path) reports the same status and code hash whether it
+    is read as an unpacked folder or from a "<module>.module" archive."""
+    module = PlainModule("pr_solo.plain", tmp_build_folder, [fixtures_dir])
+    _setup_full_module(module, frid="1")
+    folder_status = module.get_module_render_status()
+    folder_hash = module.get_module_code_hash()
+
+    _archive_module(module)  # zip in place, remove the folder
+    module.materialize()
+
+    assert module.get_module_render_status() == folder_status
+    assert module.get_module_code_hash() == folder_hash
+    module.cleanup_scratch()
+
+
+def test_code_hash_is_location_independent(fixtures_dir):
+    """The code hash depends only on content, not the build folder's absolute path, so it is stable
+    across directories/machines. This is what makes .module archives distributable: consuming the
+    same code at a different location must not report a spurious 'required module code changed'."""
+    with tempfile.TemporaryDirectory() as build_a, tempfile.TemporaryDirectory() as build_b:
+        mod_a = PlainModule("pr_solo.plain", build_a, [fixtures_dir])
+        mod_b = PlainModule("pr_solo.plain", build_b, [fixtures_dir])
+        for mod in (mod_a, mod_b):
+            os.makedirs(mod.module_build_folder, exist_ok=True)
+            (Path(mod.module_build_folder) / "main.py").write_text("print('hi')\n")
+
+        assert mod_a.module_build_folder != mod_b.module_build_folder
+        assert mod_a.get_module_code_hash() == mod_b.get_module_code_hash()
+
+
+def test_archive_has_conformance_tests(solo_module):
+    _setup_full_module(solo_module)  # code/ + tests/
+    _archive_module(solo_module)
+    assert solo_module.archive_has_conformance_tests() is True
+
+
+def test_code_only_archive_materializes_without_tests(solo_module):
+    """A module rendered with conformance tests off has no tests/, so its archive has none. It must
+    still validate and materialize (tests/ is optional)."""
+    _init_repo_with_finished_frid(solo_module.module_build_folder, solo_module.module_name, "1")
+    _write_metadata(solo_module, {"source_hash": "seed"})
+    _archive_module(solo_module)  # code/ + .codeplain, no tests/
+
+    assert solo_module.archive_has_conformance_tests() is False
+    assert solo_module.is_archived_only()
+
+    solo_module.materialize()  # must not raise
+    assert os.path.isdir(os.path.join(solo_module.module_build_folder, ".git"))
+    assert not os.path.isdir(solo_module.module_conformance_tests_folder)
+    solo_module.cleanup_scratch()
+
+
+def test_ensure_module_unpacked_code_only_archive(solo_module):
+    _init_repo_with_finished_frid(solo_module.module_build_folder, solo_module.module_name, "1")
+    _archive_module(solo_module)  # code/ only
+
+    solo_module.ensure_module_unpacked()
+    assert os.path.isdir(os.path.join(solo_module._default_module_folder, "code", ".git"))
+    assert not os.path.isdir(os.path.join(solo_module._default_module_folder, "tests"))
+    assert not os.path.exists(solo_module.module_archive_path)
+
+
+def test_materialize_rejects_non_zip(solo_module):
+    with open(solo_module.module_archive_path, "w") as f:
+        f.write("not a zip")
+    with pytest.raises(InvalidModuleArchiveError):
+        solo_module.materialize()
+    assert solo_module._scratch_dir is None
+
+
+def test_materialize_rejects_missing_subfolders(solo_module):
+    with zipfile.ZipFile(solo_module.module_archive_path, "w") as zf:
+        zf.writestr("code/marker.txt", "x")  # tests/ missing, and no .git
+    with pytest.raises(InvalidModuleArchiveError):
+        solo_module.materialize()
+
+
+def test_materialize_rejects_missing_git_repo(solo_module):
+    """code/ and tests/ present but without a .git directory is rejected."""
+    with zipfile.ZipFile(solo_module.module_archive_path, "w") as zf:
+        zf.writestr("code/main.py", "print('x')")
+        zf.writestr("tests/test_main.py", "def test_x(): pass")
+    with pytest.raises(InvalidModuleArchiveError):
+        solo_module.materialize()
+
+
+def test_materialize_rejects_zip_slip(solo_module):
+    with zipfile.ZipFile(solo_module.module_archive_path, "w") as zf:
+        zf.writestr("../escape.txt", "x")
+    with pytest.raises(InvalidModuleArchiveError):
+        solo_module.materialize()
+
+
+def test_ensure_module_unpacked_leaves_no_partial_on_invalid_archive(solo_module):
+    default = solo_module._default_module_folder
+    with zipfile.ZipFile(solo_module.module_archive_path, "w") as zf:
+        zf.writestr("code/marker.txt", "x")  # invalid layout
+    with pytest.raises(InvalidModuleArchiveError):
+        solo_module.ensure_module_unpacked()
+    assert not os.path.exists(default)  # no half-written module folder
+    assert os.path.isfile(solo_module.module_archive_path)  # archive preserved on failure
+
+
 # --------------------------------------------------------------------------
 # seed_module_metadata
 # --------------------------------------------------------------------------

tests/test_plainfileparser.py

@@ -36,7 +36,7 @@ def test_unknown_section():
     with pytest.raises(
         Exception,
         match=re.escape(
-            "Syntax error at line 3: Invalid specification heading (`Unknown Section:`). Allowed headings: definitions, implementation reqs, test reqs, functional specs, acceptance tests"
+            "Syntax error at line 4: Invalid specification heading (`Unknown Section:`). Allowed headings: definitions, implementation reqs, test reqs, functional specs, acceptance tests"
         ),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])
@@ -50,7 +50,7 @@ def test_duplicate_section():
 """
     with pytest.raises(
         Exception,
-        match=re.escape("Syntax error at line 3: Duplicate specification heading (`definitions`)"),
+        match=re.escape("Syntax error at line 4: Duplicate specification heading (`definitions`)"),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])
 
@@ -64,11 +64,48 @@ code block
 """
     with pytest.raises(
         Exception,
-        match=re.escape("Syntax error at line 2: Invalid source structure  (`code block`)"),
+        match=re.escape("Syntax error at line 3: Invalid source structure  (`code block`)"),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])
 
 
+def test_syntax_error_line_number_accounts_for_frontmatter():
+    plain_source = """---
+description: 'Plain file with frontmatter'
+---
+
+***definitions***
+
+***Unknown Section:***
+"""
+    with pytest.raises(
+        Exception,
+        match=re.escape("Syntax error at line 7: Invalid specification heading (`Unknown Section:`)"),
+    ):
+        plain_file.parse_plain_source(plain_source, {}, [], [], [])
+
+
+def test_syntax_error_line_number_with_windows_line_endings():
+    plain_source = (
+        "---\r\n"
+        "description: 'Plain file with frontmatter'\r\n"
+        "---\r\n"
+        "\r\n"
+        "***definitions***\r\n"
+        "\r\n"
+        "***Unknown Section:***\r\n"
+    )
+    with pytest.raises(
+        Exception,
+        match=re.escape("Syntax error at line 7: Invalid specification heading (`Unknown Section:`)"),
+    ):
+        plain_file.parse_plain_source(plain_source, {}, [], [], [])
+
+
+def test_normalize_line_endings_does_not_duplicate_newlines():
+    assert plain_file.normalize_line_endings("a\r\nb\rc\nd") == "a\nb\nc\nd"
+
+
 def test_plain_file_parser_with_comments(get_test_data_path):
     _, plain_sections, _ = plain_file.plain_file_parser(
         "plain_file_parser_with_comments.plain",
@@ -423,7 +460,7 @@ def test_acceptance_tests_top_level_rejected():
     with pytest.raises(
         PlainSyntaxError,
         match=re.escape(
-            "Syntax error at line 1: acceptance tests heading should be nested under specific functional spec."
+            "Syntax error at line 2: acceptance tests heading should be nested under specific functional spec."
         ),
     ):
         plain_file.parse_plain_source(plain_source, {}, [], [], [])