claude-dev-env 1.77.0 → 1.79.0

package/hooks/blocking/test_code_rules_enforcer_docstring_mark_glyph_enumeration.py

@@ -0,0 +1,262 @@
+"""Tests for check_docstring_punctuation_mark_enumeration_coverage — O6 glyph drift.
+
+A module defines a tuple of punctuation-mark glyphs (an em-dash, a spaced
+double-hyphen, a semicolon) and a docstring enumerates those marks by their
+English names while omitting one the tuple holds. The prose names two marks but
+the detection set holds three, so a reader who trusts the enumeration believes a
+mark that is active never triggers the check. This is the deterministic
+glyph-prose slice of Category O6 docstring-prose-vs-implementation drift, the
+companion to check_docstring_tuple_enumeration_match for glyph members named in
+prose rather than identifier members named in inline code.
+"""
+
+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_docstring_punctuation_mark_enumeration_coverage(
+    content: str, file_path: str
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_punctuation_mark_enumeration_coverage(
+        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/runon_detector.py"
+TEST_FILE_PATH = "/project/src/test_runon_detector.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/code_rules_docstrings.py"
+
+
+def _drifted_two_marks_named_function() -> str:
+    return (
+        'ALL_RUNON_JOINER_MARKERS = ("—", " -- ", ";")\n'
+        "\n"
+        "\n"
+        "def _sentence_carries_joiner(sentence_text: str) -> bool:\n"
+        '    """Report whether the sentence chains clauses with a joiner mark.\n'
+        "\n"
+        "    The run-on marks are an em-dash or a semicolon, the two glyphs that\n"
+        "    fuse independent clauses into one dense sentence.\n"
+        '    """\n'
+        "    return any(each in sentence_text for each in ALL_RUNON_JOINER_MARKERS)\n"
+    )
+
+
+def _complete_three_marks_named_function() -> str:
+    return (
+        'ALL_RUNON_JOINER_MARKERS = ("—", " -- ", ";")\n'
+        "\n"
+        "\n"
+        "def _sentence_carries_joiner(sentence_text: str) -> bool:\n"
+        '    """Report whether the sentence chains clauses with a joiner mark.\n'
+        "\n"
+        "    The run-on marks are an em-dash, a spaced double-hyphen, or a\n"
+        "    semicolon, the glyphs that fuse independent clauses into one\n"
+        "    dense sentence.\n"
+        '    """\n'
+        "    return any(each in sentence_text for each in ALL_RUNON_JOINER_MARKERS)\n"
+    )
+
+
+def _single_mark_named_function() -> str:
+    return (
+        'ALL_RUNON_JOINER_MARKERS = ("—", " -- ", ";")\n'
+        "\n"
+        "\n"
+        "def _sentence_carries_joiner(sentence_text: str) -> bool:\n"
+        '    """Report whether the sentence chains clauses with an em-dash.\n'
+        "\n"
+        "    The em-dash is the glyph that fuses clauses into one sentence.\n"
+        '    """\n'
+        "    return any(each in sentence_text for each in ALL_RUNON_JOINER_MARKERS)\n"
+    )
+
+
+def _non_glyph_tuple_function() -> str:
+    return (
+        'ALL_OUTCOME_LABELS = ("alpha", "beta", "gamma")\n'
+        "\n"
+        "\n"
+        "def describe_outcome(label_text: str) -> bool:\n"
+        '    """Report the outcome named by an em-dash or a semicolon label.\n'
+        "\n"
+        "    The labels carry a semicolon between the segments of each name.\n"
+        '    """\n'
+        "    return label_text in ALL_OUTCOME_LABELS\n"
+    )
+
+
+def test_should_flag_omitted_double_hyphen_mark() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _drifted_two_marks_named_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("--" in each for each in issues), (
+        f"The docstring naming em-dash and semicolon but omitting the double-hyphen "
+        f"that ALL_RUNON_JOINER_MARKERS holds must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_report_category_o6_in_the_message() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _drifted_two_marks_named_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("O6" in each for each in issues), (
+        f"Expected the Category O6 label in the message, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_complete_enumeration() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _complete_three_marks_named_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"A docstring naming all three marks must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_single_named_mark_below_threshold() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _single_mark_named_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"A docstring naming a single mark is not an enumeration, got: {issues!r}"
+
+
+def test_should_not_flag_non_glyph_tuple() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _non_glyph_tuple_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"A tuple of non-punctuation members must not be flagged, got: {issues!r}"
+
+
+def test_should_flag_on_hook_infrastructure_where_the_drift_lives() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _drifted_two_marks_named_function(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert any("--" in each for each in issues), (
+        f"The drift lives in hook modules, so the gate must run there, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _drifted_two_marks_named_function(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    unparseable_naming_marks = 'def fetch(\n    """An em-dash and a semicolon."""\n'
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        unparseable_naming_marks, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def _drifted_annotated_tuple_function() -> str:
+    return (
+        'ALL_RUNON_JOINER_MARKERS: tuple[str, ...] = ("—", " -- ", ";")\n'
+        "\n"
+        "\n"
+        "def _sentence_carries_joiner(sentence_text: str) -> bool:\n"
+        '    """Report whether the sentence chains clauses with a joiner mark.\n'
+        "\n"
+        "    The run-on marks are an em-dash or a semicolon.\n"
+        '    """\n'
+        "    return any(each in sentence_text for each in ALL_RUNON_JOINER_MARKERS)\n"
+    )
+
+
+def test_should_flag_annotated_same_module_tuple_drift() -> None:
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        _drifted_annotated_tuple_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("--" in each for each in issues), (
+        f"An annotated marker tuple in the same module must be checked, got: {issues!r}"
+    )
+
+
+def test_should_flag_drift_against_imported_companion_tuple(tmp_path: Path) -> None:
+    companion_directory = tmp_path / "marks_package"
+    companion_directory.mkdir()
+    (companion_directory / "joiner_marks.py").write_text(
+        'ALL_RUNON_JOINER_MARKERS: tuple[str, ...] = ("—", " -- ", ";")\n',
+        encoding="utf-8",
+    )
+    consumer_directory = tmp_path / "blocking"
+    consumer_directory.mkdir()
+    consumer_source = (
+        "from marks_package.joiner_marks import ALL_RUNON_JOINER_MARKERS\n"
+        "\n"
+        "\n"
+        "def _sentence_carries_joiner(sentence_text: str) -> bool:\n"
+        '    """Report whether the sentence chains clauses with a joiner mark.\n'
+        "\n"
+        "    The run-on marks are an em-dash or a semicolon, the two glyphs that\n"
+        "    fuse independent clauses into one dense sentence.\n"
+        '    """\n'
+        "    return any(each in sentence_text for each in ALL_RUNON_JOINER_MARKERS)\n"
+    )
+    consumer_path = consumer_directory / "runon_consumer.py"
+    consumer_path.write_text(consumer_source, encoding="utf-8")
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        consumer_source, str(consumer_path)
+    )
+    assert any("--" in each for each in issues), (
+        f"A docstring drifting from an imported companion marker tuple must be "
+        f"flagged so the split-file shape is caught, got: {issues!r}"
+    )
+
+
+def test_should_not_resolve_companion_when_no_marks_named(tmp_path: Path) -> None:
+    companion_directory = tmp_path / "marks_package"
+    companion_directory.mkdir()
+    (companion_directory / "joiner_marks.py").write_text(
+        'ALL_RUNON_JOINER_MARKERS: tuple[str, ...] = ("—", " -- ", ";")\n',
+        encoding="utf-8",
+    )
+    consumer_directory = tmp_path / "blocking"
+    consumer_directory.mkdir()
+    consumer_source = (
+        "from marks_package.joiner_marks import ALL_RUNON_JOINER_MARKERS\n"
+        "\n"
+        "\n"
+        "def _sentence_carries_joiner(sentence_text: str) -> bool:\n"
+        '    """Report whether the sentence carries any joiner glyph."""\n'
+        "    return any(each in sentence_text for each in ALL_RUNON_JOINER_MARKERS)\n"
+    )
+    consumer_path = consumer_directory / "runon_consumer.py"
+    consumer_path.write_text(consumer_source, encoding="utf-8")
+    issues = check_docstring_punctuation_mark_enumeration_coverage(
+        consumer_source, str(consumer_path)
+    )
+    assert issues == [], (
+        f"A docstring naming no marks must not be flagged, got: {issues!r}"
+    )
+
+
+def test_validate_content_surfaces_mark_glyph_drift() -> None:
+    issues = validate_content(
+        _drifted_two_marks_named_function(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [each for each in issues if "--" in each and "O6" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 mark-glyph drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_docstring_no_network.py

@@ -0,0 +1,115 @@
+"""Tests for check_docstring_no_network_claim_with_metadata_access — Category O6.
+
+A docstring promising a code path returns "without touching the network" drifts
+when the body calls a path-metadata method (``is_file``, ``stat``, ...): on a
+network share each metadata call is a round-trip over the wire, so the no-network
+claim is false. This is the deterministic slice of Category O6 (docstring prose
+versus implementation drift) for a no-network claim.
+"""
+
+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_docstring_no_network_claim(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_no_network_claim_with_metadata_access(
+        content, file_path
+    )
+
+
+PRODUCTION_FILE_PATH = "/project/shared_utils/bws/secret_fetch.py"
+TEST_FILE_PATH = "/project/shared_utils/bws/tests/test_secret_fetch.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def test_flags_no_network_claim_with_is_file_and_stat() -> None:
+    content = (
+        "def _ensure_local_bws_cache() -> str:\n"
+        '    """Return the local cache path, repopulating when stale.\n'
+        "\n"
+        "    An existing cache is returned without touching the network; a\n"
+        "    missing or size-mismatched cache is repopulated from the bundled\n"
+        "    executable.\n"
+        '    """\n'
+        "    if BUNDLED_BWS_EXECUTABLE_PATH.is_file():\n"
+        "        bundled_size = BUNDLED_BWS_EXECUTABLE_PATH.stat().st_size\n"
+        "        return str(LOCAL_BWS_CACHE_PATH)\n"
+        "    return str(LOCAL_BWS_CACHE_PATH)\n"
+    )
+    issues = check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "_ensure_local_bws_cache" in issues[0]
+    assert "without touching the network" in issues[0]
+
+
+def test_flags_no_network_access_phrase_with_exists() -> None:
+    content = (
+        "def read_warm_cache(cache_path) -> str:\n"
+        '    """Serve the warm cache with no network access."""\n'
+        "    if cache_path.exists():\n"
+        "        return cache_path.read_text()\n"
+        "    return ''\n"
+    )
+    assert len(check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH)) == 1
+
+
+def test_passes_when_claim_present_but_no_metadata_access() -> None:
+    content = (
+        "def read_warm_cache(cache_path) -> str:\n"
+        '    """Serve the warm cache without touching the network."""\n'
+        "    return cache_path.read_text()\n"
+    )
+    assert check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_metadata_access_but_no_network_claim() -> None:
+    content = (
+        "def _ensure_local_bws_cache(share_path) -> str:\n"
+        '    """Return the local cache path, repopulating when stale.\n'
+        "\n"
+        "    The bundled share is stat-checked on every call to validate the\n"
+        "    cache against the bundled executable size.\n"
+        '    """\n'
+        "    if share_path.is_file():\n"
+        "        return str(share_path)\n"
+        "    return ''\n"
+    )
+    assert check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    content = (
+        "def _ensure_local_bws_cache(share_path) -> str:\n"
+        '    """Return the cache without touching the network."""\n'
+        "    if share_path.is_file():\n"
+        "        return str(share_path)\n"
+        "    return ''\n"
+    )
+    assert check_docstring_no_network_claim(content, TEST_FILE_PATH) == []
+
+
+def test_hook_infrastructure_is_exempt() -> None:
+    content = (
+        "def _ensure_local_bws_cache(share_path) -> str:\n"
+        '    """Return the cache without touching the network."""\n'
+        "    if share_path.is_file():\n"
+        "        return str(share_path)\n"
+        "    return ''\n"
+    )
+    assert check_docstring_no_network_claim(content, HOOK_INFRASTRUCTURE_PATH) == []

package/hooks/blocking/test_code_rules_enforcer_docstring_raises_largezipfile.py

@@ -0,0 +1,226 @@
+"""Tests for check_docstring_raises_unraisable_largezipfile — O6 Raises drift.
+
+A function's docstring Raises clause lists ``zipfile.LargeZipFile`` while the
+function opens its ``zipfile.ZipFile`` writer with ZIP64 permitted (``allowZip64``
+left at its default of True). The stdlib raises ``LargeZipFile`` only when an
+entry needs ZIP64 AND ``allowZip64`` is False; with ZIP64 permitted the writer
+transparently uses it and never raises. The Raises entry therefore documents an
+exception the body cannot produce — the deterministic slice of Category O6
+docstring-prose-vs-implementation drift where a writer-opened-with-default-ZIP64
+disagrees with a LargeZipFile Raises clause.
+"""
+
+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_docstring_raises_unraisable_largezipfile(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_raises_unraisable_largezipfile(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/stp_archive.py"
+TEST_FILE_PATH = "/project/src/test_stp_archive.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _default_zip64_writer_documenting_largezipfile() -> str:
+    return (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def rewrite_stp_member_atomically(stp_path: Path, member_bytes: bytes) -> None:\n"
+        '    """Rewrite one member of an STP in place via a temp sibling.\n'
+        "\n"
+        "    Raises:\n"
+        "        OSError: When the streaming write or the rename fails.\n"
+        "        zipfile.BadZipFile: When the source archive is not a valid ZIP.\n"
+        "        zipfile.LargeZipFile: When an entry needs ZIP64 the writer forbids.\n"
+        '    """\n'
+        "    with zipfile.ZipFile(stp_path, 'r') as source_archive:\n"
+        "        with zipfile.ZipFile(stp_path, 'w', zipfile.ZIP_DEFLATED) as target_archive:\n"
+        "            target_archive.writestr('IM/a.png', member_bytes)\n"
+    )
+
+
+def test_should_flag_largezipfile_over_a_default_zip64_writer() -> None:
+    issues = check_docstring_raises_unraisable_largezipfile(
+        _default_zip64_writer_documenting_largezipfile(), PRODUCTION_FILE_PATH
+    )
+    assert any("LargeZipFile" in each for each in issues), (
+        f"A LargeZipFile Raises entry over a default-ZIP64 writer must flag, got: {issues!r}"
+    )
+
+
+def test_should_report_category_o6_in_the_message() -> None:
+    issues = check_docstring_raises_unraisable_largezipfile(
+        _default_zip64_writer_documenting_largezipfile(), PRODUCTION_FILE_PATH
+    )
+    assert any("O6" in each for each in issues), (
+        f"Expected the Category O6 label in the message, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_writer_forbids_zip64_via_keyword() -> None:
+    source = (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def rewrite(stp_path: Path, member_bytes: bytes) -> None:\n"
+        '    """Rewrite one member of an STP, forbidding ZIP64.\n'
+        "\n"
+        "    Raises:\n"
+        "        zipfile.LargeZipFile: When an entry needs ZIP64 the writer forbids.\n"
+        '    """\n'
+        "    with zipfile.ZipFile(stp_path, 'w', allowZip64=False) as target_archive:\n"
+        "        target_archive.writestr('IM/a.png', member_bytes)\n"
+    )
+    issues = check_docstring_raises_unraisable_largezipfile(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A writer that forbids ZIP64 can raise LargeZipFile, so the clause is valid, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_writer_forbids_zip64_positionally() -> None:
+    source = (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def rewrite(stp_path: Path, member_bytes: bytes) -> None:\n"
+        '    """Rewrite one member of an STP, forbidding ZIP64.\n'
+        "\n"
+        "    Raises:\n"
+        "        zipfile.LargeZipFile: When an entry needs ZIP64 the writer forbids.\n"
+        '    """\n'
+        "    with zipfile.ZipFile(stp_path, 'w', zipfile.ZIP_DEFLATED, False) as target_archive:\n"
+        "        target_archive.writestr('IM/a.png', member_bytes)\n"
+    )
+    issues = check_docstring_raises_unraisable_largezipfile(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A positional allowZip64=False keeps the clause valid, got: {issues!r}"
+
+
+def test_should_not_flag_when_function_opens_no_zip_writer() -> None:
+    source = (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def patch_via_helper(stp_path: Path, member_bytes: bytes) -> None:\n"
+        '    """Patch one member through a helper writer.\n'
+        "\n"
+        "    Raises:\n"
+        "        zipfile.LargeZipFile: When the helper writer forbids ZIP64.\n"
+        '    """\n'
+        "    write_member(stp_path, member_bytes)\n"
+    )
+    issues = check_docstring_raises_unraisable_largezipfile(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"With no visible writer the exception may propagate from a callee, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_read_only_open() -> None:
+    source = (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def read_member(stp_path: Path) -> bytes:\n"
+        '    """Read one member of an STP.\n'
+        "\n"
+        "    Raises:\n"
+        "        zipfile.LargeZipFile: When an entry needs ZIP64 the writer forbids.\n"
+        '    """\n'
+        "    with zipfile.ZipFile(stp_path) as source_archive:\n"
+        "        return source_archive.read('IM/a.png')\n"
+    )
+    issues = check_docstring_raises_unraisable_largezipfile(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A read-only open has no write-mode writer, so it is left alone, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_raises_omits_largezipfile() -> None:
+    source = (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def rewrite(stp_path: Path, member_bytes: bytes) -> None:\n"
+        '    """Rewrite one member of an STP in place.\n'
+        "\n"
+        "    Raises:\n"
+        "        OSError: When the streaming write or the rename fails.\n"
+        '    """\n'
+        "    with zipfile.ZipFile(stp_path, 'w', zipfile.ZIP_DEFLATED) as target_archive:\n"
+        "        target_archive.writestr('IM/a.png', member_bytes)\n"
+    )
+    issues = check_docstring_raises_unraisable_largezipfile(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A Raises clause without LargeZipFile must not flag, got: {issues!r}"
+
+
+def test_should_flag_when_mode_passed_by_keyword() -> None:
+    source = (
+        "import zipfile\n"
+        "from pathlib import Path\n"
+        "\n"
+        "def rewrite(stp_path: Path, member_bytes: bytes) -> None:\n"
+        '    """Rewrite one member of an STP in place.\n'
+        "\n"
+        "    Raises:\n"
+        "        zipfile.LargeZipFile: When an entry needs ZIP64 the writer forbids.\n"
+        '    """\n'
+        "    with zipfile.ZipFile(stp_path, mode='w') as target_archive:\n"
+        "        target_archive.writestr('IM/a.png', member_bytes)\n"
+    )
+    issues = check_docstring_raises_unraisable_largezipfile(source, PRODUCTION_FILE_PATH)
+    assert any("LargeZipFile" in each for each in issues), (
+        f"A keyword mode='w' writer with default ZIP64 must flag, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_raises_unraisable_largezipfile(
+        _default_zip64_writer_documenting_largezipfile(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_raises_unraisable_largezipfile(
+        _default_zip64_writer_documenting_largezipfile(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_raises_unraisable_largezipfile("def rewrite(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_largezipfile_drift() -> None:
+    issues = validate_content(
+        _default_zip64_writer_documenting_largezipfile(),
+        PRODUCTION_FILE_PATH,
+        old_content="",
+    )
+    matching_issues = [each for each in issues if "LargeZipFile" in each and "O6" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 LargeZipFile drift, got: {issues!r}"
+    )