claude-dev-env 1.78.0 → 1.79.0

package/hooks/blocking/test_code_rules_enforcer_docstring_unreferenced_param.py

@@ -0,0 +1,160 @@
+"""Tests for check_docstring_documents_unreferenced_parameter.
+
+A parameter named in the ``Args:`` block but referenced nowhere in the body is
+dead: the function does not read it, yet the docstring describes behavior keyed
+to it. The common shape is a flag a caller wired in before the real logic moved
+up a level, leaving the parameter and its Args line claiming a behavior the body
+does not implement.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_documents_unreferenced_parameter(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_documents_unreferenced_parameter(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/per_theme_loop.py"
+TEST_FILE_PATH = "/project/src/test_per_theme_loop.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _function_with_dead_documented_flag() -> str:
+    return (
+        "def run_per_theme_loop_and_finalize(themes: list, is_no_notify: bool) -> int:\n"
+        '    """Run the per-theme loop and finalize the report.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses opening the HTML report.\n"
+        "\n"
+        "    Returns:\n"
+        "        The resolved exit code.\n"
+        '    """\n'
+        "    exit_code = 0\n"
+        "    for each_theme in themes:\n"
+        "        exit_code = max(exit_code, each_theme.run())\n"
+        "    render_and_write_html_report(themes)\n"
+        "    return exit_code\n"
+    )
+
+
+def test_should_flag_documented_parameter_never_referenced() -> None:
+    issues = check_documents_unreferenced_parameter(
+        _function_with_dead_documented_flag(), PRODUCTION_FILE_PATH
+    )
+    assert any("is_no_notify" in each for each in issues), (
+        f"Expected dead 'is_no_notify' flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_parameter_referenced_in_body() -> None:
+    source = (
+        "def run_per_theme_loop_and_finalize(themes: list, is_no_notify: bool) -> int:\n"
+        '    """Run the per-theme loop and finalize the report.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses opening the HTML report.\n"
+        "\n"
+        "    Returns:\n"
+        "        The resolved exit code.\n"
+        '    """\n'
+        "    exit_code = 0\n"
+        "    for each_theme in themes:\n"
+        "        exit_code = max(exit_code, each_theme.run())\n"
+        "    if not is_no_notify:\n"
+        "        open_html_report(themes)\n"
+        "    return exit_code\n"
+    )
+    issues = check_documents_unreferenced_parameter(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Referenced parameter must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_when_kwargs_present() -> None:
+    source = (
+        "def render(themes: list, is_no_notify: bool, **overrides) -> int:\n"
+        '    """Render the report.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses opening the report.\n"
+        '    """\n'
+        "    settings = dict(overrides)\n"
+        "    for each_theme in themes:\n"
+        "        each_theme.render(settings)\n"
+        "    return 0\n"
+    )
+    issues = check_documents_unreferenced_parameter(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"**kwargs functions must be skipped, got: {issues!r}"
+
+
+def test_should_skip_private_function() -> None:
+    source = (
+        "def _drive(themes: list, is_no_notify: bool) -> int:\n"
+        '    """Drive internally.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses the report.\n"
+        '    """\n'
+        "    exit_code = 0\n"
+        "    for each_theme in themes:\n"
+        "        exit_code = max(exit_code, each_theme.run())\n"
+        "    return exit_code\n"
+    )
+    issues = check_documents_unreferenced_parameter(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private functions exempt, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_documents_unreferenced_parameter(
+        _function_with_dead_documented_flag(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_documents_unreferenced_parameter(
+        _function_with_dead_documented_flag(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_documents_unreferenced_parameter("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_unreferenced_parameter() -> None:
+    issues = validate_content(
+        _function_with_dead_documented_flag(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [
+        each for each in issues if "is_no_notify" in each and "never references" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the dead-parameter issue, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_module_docstring_data_schema_scope.py

@@ -0,0 +1,82 @@
+"""Tests for check_module_docstring_scope_omits_data_schema_constants (Category O).
+
+A module whose one-line docstring scopes its contents to user-facing text while
+the body also defines serialization field keys, run-metadata schema keys, or
+runtime config under-describes the module — the Category O module-responsibility
+drift. The gate fires only when the docstring claims a user-facing-text scope and
+acknowledges no data-schema or runtime-config category, so broadening the summary
+to name the data-schema keys and runtime config clears it.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_scope(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_module_docstring_scope_omits_data_schema_constants(
+        content, file_path
+    )
+
+
+PRODUCTION_FILE_PATH = "/project/stp_contrast_fix/config/messages.py"
+TEST_FILE_PATH = "/project/stp_contrast_fix/config/test_messages.py"
+
+USER_FACING_SUMMARY = '"""User-facing strings: CLI flag names, help text, and log messages."""\n'
+DATA_SCHEMA_BODY = (
+    "from typing import Final\n"
+    'CLI_FLAG_EXECUTE: Final[str] = "--execute"\n'
+    'JSONL_FIELD_STP_PATH: Final[str] = "stp_path"\n'
+    'RUN_METADATA_CLI_ARG_KEY_LIMIT: Final[str] = "limit"\n'
+    'STDOUT_ENCODING: Final[str] = "utf-8"\n'
+    'MAIN_LOGGING_FORMAT_STRING: Final[str] = "%(message)s"\n'
+)
+
+
+def test_flags_user_facing_summary_over_data_schema_constants() -> None:
+    issues = check_scope(USER_FACING_SUMMARY + DATA_SCHEMA_BODY, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "JSONL_FIELD_STP_PATH" in issues[0]
+    assert "RUN_METADATA_CLI_ARG_KEY_LIMIT" in issues[0]
+    assert "module-responsibility drift" in issues[0]
+
+
+def test_passes_when_summary_acknowledges_data_schema_scope() -> None:
+    acknowledging_summary = (
+        '"""User-facing strings plus per-theme JSONL field keys, run-metadata '
+        'schema keys, and runtime config."""\n'
+    )
+    assert check_scope(acknowledging_summary + DATA_SCHEMA_BODY, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_module_has_no_data_schema_constants() -> None:
+    strings_only_body = (
+        "from typing import Final\n"
+        'CLI_FLAG_EXECUTE: Final[str] = "--execute"\n'
+        'CLI_FLAG_LIMIT: Final[str] = "--limit"\n'
+    )
+    assert check_scope(USER_FACING_SUMMARY + strings_only_body, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_summary_does_not_claim_user_facing_scope() -> None:
+    non_user_facing_summary = '"""Theme-database column names and SQL templates."""\n'
+    assert check_scope(non_user_facing_summary + DATA_SCHEMA_BODY, PRODUCTION_FILE_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    assert check_scope(USER_FACING_SUMMARY + DATA_SCHEMA_BODY, TEST_FILE_PATH) == []

package/hooks/blocking/test_code_rules_enforcer_paired_test.py

@@ -21,9 +21,15 @@ if str(_BLOCKING_DIRECTORY) not in sys.path:
 
 from code_rules_paired_test import (  # noqa: E402
     check_public_function_missing_paired_test,
+    check_test_file_omits_module_public_function,
 )
 
 _TWO_PUBLIC_FUNCTIONS = "def alpha():\n    return 1\n\n\ndef beta():\n    return 2\n"
+_THREE_PUBLIC_FUNCTIONS = (
+    "def alpha():\n    return 1\n\n\n"
+    "def beta():\n    return 2\n\n\n"
+    "def gamma():\n    return 3\n"
+)
 
 
 @pytest.fixture
@@ -97,6 +103,29 @@ def test_skips_when_suite_covers_no_public_function(
     assert all_issues == []
 
 
+def test_flags_public_surface_when_suite_exercises_only_private_helper(
+    neutral_package_directory: Path,
+) -> None:
+    module_source = (
+        "def _aarrggbb_to_css(value):\n    return value\n\n\n"
+        "def render_table():\n    return _aarrggbb_to_css('x')\n\n\n"
+        "def render_summary():\n    return 2\n"
+    )
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import _aarrggbb_to_css\n\n"
+        "def test_helper():\n    assert _aarrggbb_to_css('x') == 'x'\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        module_source, str(neutral_package_directory / "mod.py")
+    )
+    assert len(all_issues) == 2
+    flagged_names = " ".join(all_issues)
+    assert "render_table" in flagged_names
+    assert "render_summary" in flagged_names
+
+
 def test_counts_coverage_across_sibling_test_files(
     neutral_package_directory: Path,
 ) -> None:
@@ -147,3 +176,164 @@ def test_exempts_hook_infrastructure_and_test_paths(
     test_path = str(neutral_package_directory / "tests" / "test_mod.py")
     assert check_public_function_missing_paired_test(_TWO_PUBLIC_FUNCTIONS, hook_path) == []
     assert check_public_function_missing_paired_test(_TWO_PUBLIC_FUNCTIONS, test_path) == []
+
+
+def _write_module(package_directory: Path, body: str) -> None:
+    (package_directory / "mod.py").write_text(body, encoding="utf-8")
+
+
+_SUITE_COVERS_ALPHA_BETA = (
+    "from pkg.mod import alpha, beta\n\n"
+    "def test_pair():\n    assert alpha() == 1 and beta() == 2\n"
+)
+
+
+def test_flags_module_public_function_when_test_suite_omits_it(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert len(all_issues) == 1
+    assert "gamma" in all_issues[0]
+    assert "mod.py" in all_issues[0]
+    assert "alpha" not in all_issues[0]
+    assert "beta" not in all_issues[0]
+
+
+def test_clean_when_test_suite_covers_every_module_public_function(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    suite_covers_all = (
+        "from pkg.mod import alpha, beta, gamma\n\n"
+        "def test_all():\n    assert alpha() and beta() and gamma()\n"
+    )
+    all_issues = check_test_file_omits_module_public_function(suite_covers_all, test_path)
+    assert all_issues == []
+
+
+def test_skips_when_test_suite_covers_no_module_public_function(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        "def test_unrelated():\n    assert 1 + 1 == 2\n", test_path
+    )
+    assert all_issues == []
+
+
+def test_skips_test_file_with_no_paired_production_module(
+    neutral_package_directory: Path,
+) -> None:
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert all_issues == []
+
+
+def test_ignores_a_non_stem_matched_written_file(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    helper_path = str(neutral_package_directory / "helper.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, helper_path
+    )
+    assert all_issues == []
+
+
+def test_resolves_production_module_beside_the_test_file(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    beside_test_path = str(neutral_package_directory / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, beside_test_path
+    )
+    assert len(all_issues) == 1
+    assert "gamma" in all_issues[0]
+
+
+def test_judges_post_edit_content_over_stale_on_disk_test(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        _SUITE_COVERS_ALPHA_BETA,
+    )
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    post_edit_covers_all = (
+        "from pkg.mod import alpha, beta, gamma\n\n"
+        "def test_all():\n    assert alpha() and beta() and gamma()\n"
+    )
+    all_issues = check_test_file_omits_module_public_function(
+        post_edit_covers_all, test_path
+    )
+    assert all_issues == []
+
+
+def test_counts_coverage_across_sibling_test_files_on_test_write(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    _write_test_file(
+        neutral_package_directory,
+        "test_extra.py",
+        "from pkg.mod import gamma\n\ndef test_gamma():\n    assert gamma() == 3\n",
+    )
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert all_issues == []
+
+
+def test_test_side_message_names_module_and_function_without_line_prefix(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert len(all_issues) == 1
+    assert not all_issues[0].startswith("Line ")
+    assert "mod.py" in all_issues[0]
+    assert "gamma" in all_issues[0]
+
+
+def test_test_side_omission_blocks_on_any_test_file_edit(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert len(all_issues) == 1
+    assert "gamma" in all_issues[0]
+
+
+def test_skips_when_paired_production_module_is_exempt(
+    neutral_package_directory: Path,
+) -> None:
+    (neutral_package_directory / "__init__.py").write_text(
+        _THREE_PUBLIC_FUNCTIONS, encoding="utf-8"
+    )
+    beside_test_path = str(neutral_package_directory / "test___init__.py")
+    suite_covers_all = (
+        "from pkg import alpha, beta, gamma\n\n"
+        "def test_all():\n    assert alpha() and beta() and gamma()\n"
+    )
+    all_issues = check_test_file_omits_module_public_function(
+        suite_covers_all, beside_test_path
+    )
+    assert all_issues == []

package/hooks/blocking/test_code_rules_enforcer_polarity_name_contradiction.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location("code_rules_enforcer", ENFORCER_PATH)
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_FILE_PATH = "packages/app/services/foo.py"
+TEST_FILE_PATH = "packages/app/tests/test_foo.py"
+
+
+def test_should_flag_allowed_target_assigned_from_forbidden_callee() -> None:
+    source = (
+        "def offset() -> None:\n"
+        "    is_inside_allowed = _point_hits_any_forbidden(px, py, rects)\n"
+        "    return is_inside_allowed\n"
+    )
+    issues = code_rules_enforcer.check_polarity_name_contradiction(source, PRODUCTION_FILE_PATH)
+    assert any("is_inside_allowed" in each_issue for each_issue in issues), (
+        f"Expected the allowed/forbidden contradiction flagged, got: {issues}"
+    )
+
+
+def test_should_flag_attribute_callee_with_antonym() -> None:
+    source = (
+        "def gate() -> None:\n    is_enabled = self._is_disabled(state)\n    return is_enabled\n"
+    )
+    issues = code_rules_enforcer.check_polarity_name_contradiction(source, PRODUCTION_FILE_PATH)
+    assert any("is_enabled" in each_issue for each_issue in issues), (
+        f"Expected the enabled/disabled contradiction flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_callee_polarity_matches_target() -> None:
+    source = (
+        "def gate() -> None:\n"
+        "    is_allowed = _point_inside_any_allowed_rect(px, py, rects)\n"
+        "    return is_allowed\n"
+    )
+    issues = code_rules_enforcer.check_polarity_name_contradiction(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Matching polarity must pass, got: {issues}"
+
+
+def test_should_not_flag_neutral_callee() -> None:
+    source = (
+        "def gate() -> None:\n"
+        "    is_allowed = _point_inside_any_rect(px, py, rects)\n"
+        "    return is_allowed\n"
+    )
+    issues = code_rules_enforcer.check_polarity_name_contradiction(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Neutral callee must pass, got: {issues}"
+
+
+def test_should_not_flag_substring_only_token_match() -> None:
+    source = (
+        "def gate() -> None:\n"
+        "    is_disallowed_count = compute_blocked_total(rects)\n"
+        "    return is_disallowed_count\n"
+    )
+    issues = code_rules_enforcer.check_polarity_name_contradiction(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"'disallowed' embeds 'allowed' as a substring, not a whole token; must not flag, got: {issues}"
+    )
+
+
+def test_should_skip_in_test_files() -> None:
+    source = (
+        "def offset() -> None:\n"
+        "    is_inside_allowed = _point_hits_any_forbidden(px, py, rects)\n"
+        "    return is_inside_allowed\n"
+    )
+    issues = code_rules_enforcer.check_polarity_name_contradiction(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues}"

package/hooks/blocking/test_code_rules_enforcer_vacuous_cleanup_assertion.py

@@ -0,0 +1,132 @@
+"""Tests for vacuous cleanup-on-failure assertion detection.
+
+A cleanup-on-failure test that asserts no leftover temp file is left behind,
+yet never proves the temp file was created, passes vacuously: the assertion
+holds even when the on-failure cleanup is entirely broken. The gate flags that
+shape so the author arranges a post-creation failure and asserts real removal.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+TEST_FILE_PATH = "packages/app/tests/test_archive_rewrite.py"
+PRODUCTION_FILE_PATH = "packages/app/services/archive_rewrite.py"
+
+
+def test_should_flag_glob_emptiness_cleanup_test_without_temp_creation() -> None:
+    source = (
+        "def test_rewrite_removes_tmp_file_on_failure(tmp_path: Path) -> None:\n"
+        "    stp_path = build_corrupt_stp(stp_path=tmp_path / 'corrupt.stp')\n"
+        "    rewrite_properties_xml_atomically(stp_path=stp_path, patched='<x/>')\n"
+        "    all_tmp_siblings = list(tmp_path.glob('*.tmp'))\n"
+        "    assert len(all_tmp_siblings) == 0\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert any("vacuous" in issue.lower() for issue in issues), (
+        f"Expected a vacuous-cleanup issue, got: {issues}"
+    )
+
+
+def test_should_not_flag_when_post_creation_failure_is_arranged() -> None:
+    source = (
+        "def test_rewrite_removes_tmp_file_on_replace_failure(tmp_path, monkeypatch)"
+        " -> None:\n"
+        "    stp_path = build_valid_stp(stp_path=tmp_path / 'theme.stp')\n"
+        "    monkeypatch.setattr(os, 'replace', _raise_oserror)\n"
+        "    rewrite_properties_xml_atomically(stp_path=stp_path, patched='<x/>')\n"
+        "    all_tmp_siblings = list(tmp_path.glob('*.tmp'))\n"
+        "    assert len(all_tmp_siblings) == 0\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert issues == [], f"Expected no issue when failure is arranged, got: {issues}"
+
+
+def test_should_not_flag_when_temp_existence_is_proven_first() -> None:
+    source = (
+        "def test_cleanup_removes_temp_on_failure(tmp_path: Path) -> None:\n"
+        "    temporary_path = tmp_path / 'theme.stp.tmp'\n"
+        "    temporary_path.write_bytes(b'partial')\n"
+        "    assert temporary_path.exists()\n"
+        "    run_cleanup_after_failure(temporary_path)\n"
+        "    assert not list(tmp_path.glob('*.tmp'))\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert issues == [], f"Expected no issue when temp existence proven, got: {issues}"
+
+
+def test_should_not_flag_success_named_cleanup_assertion() -> None:
+    source = (
+        "def test_rewrite_leaves_no_tmp_sibling_on_success(tmp_path: Path) -> None:\n"
+        "    stp_path = build_valid_stp(stp_path=tmp_path / 'theme.stp')\n"
+        "    rewrite_properties_xml_atomically(stp_path=stp_path, patched='<x/>')\n"
+        "    all_tmp_siblings = list(tmp_path.glob('*.tmp'))\n"
+        "    assert len(all_tmp_siblings) == 0\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert issues == [], f"Expected no issue for a success-named test, got: {issues}"
+
+
+def test_should_not_flag_failure_test_asserting_real_behavior() -> None:
+    source = (
+        "def test_rewrite_reports_cleanup_failure_on_directory_tmp("
+        "tmp_path: Path) -> None:\n"
+        "    temporary_path = tmp_path / 'theme.stp.tmp'\n"
+        "    temporary_path.mkdir()\n"
+        "    write_outcome = rewrite_properties_xml_atomically("
+        "stp_path=tmp_path / 't.stp', patched='<x/>')\n"
+        "    assert write_outcome.temporary_cleanup_error_message is not None\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert issues == [], f"Expected no issue for a behavior assertion, got: {issues}"
+
+
+def test_should_not_flag_mixed_assertion_cleanup_test() -> None:
+    source = (
+        "def test_rewrite_removes_tmp_and_reports_failure(tmp_path: Path) -> None:\n"
+        "    stp_path = build_corrupt_stp(stp_path=tmp_path / 'corrupt.stp')\n"
+        "    write_outcome = rewrite_properties_xml_atomically("
+        "stp_path=stp_path, patched='<x/>')\n"
+        "    assert write_outcome.is_write_successful is False\n"
+        "    all_tmp_siblings = list(tmp_path.glob('*.tmp'))\n"
+        "    assert len(all_tmp_siblings) == 0\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert issues == [], f"Expected no issue for a mixed-assertion test, got: {issues}"
+
+
+def test_should_not_flag_in_production_files() -> None:
+    source = (
+        "def test_rewrite_removes_tmp_file_on_failure(tmp_path: Path) -> None:\n"
+        "    all_tmp_siblings = list(tmp_path.glob('*.tmp'))\n"
+        "    assert len(all_tmp_siblings) == 0\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Expected no issue in a production file, got: {issues}"
+
+
+def test_should_include_line_number_in_issue() -> None:
+    source = (
+        "def test_rewrite_removes_tmp_file_on_failure(tmp_path: Path) -> None:\n"
+        "    all_tmp_siblings = list(tmp_path.glob('*.tmp'))\n"
+        "    assert all_tmp_siblings == []\n"
+    )
+    issues = code_rules_enforcer.check_vacuous_cleanup_assertion_tests(source, TEST_FILE_PATH)
+    assert any("Line 1" in issue for issue in issues), (
+        f"Expected a line number in the issue, got: {issues}"
+    )