claude-dev-env 1.77.0 → 1.78.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_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}"
+    )

package/hooks/blocking/test_code_rules_enforcer_paired_test.py

@@ -0,0 +1,149 @@
+"""Behavioral tests for the public-function paired-test coverage check.
+
+Drives ``check_public_function_missing_paired_test`` over a real temporary
+filesystem whose path carries no ``test``/``hooks``/``config`` segment, so the
+module under test is classified as ordinary production code while its on-disk
+paired test files are read exactly as they would be in a real package.
+"""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+
+import pytest
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+if str(_BLOCKING_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIRECTORY))
+
+from code_rules_paired_test import (  # noqa: E402
+    check_public_function_missing_paired_test,
+)
+
+_TWO_PUBLIC_FUNCTIONS = "def alpha():\n    return 1\n\n\ndef beta():\n    return 2\n"
+
+
+@pytest.fixture
+def neutral_package_directory() -> Iterator[Path]:
+    """Yield a ``pkg`` directory under a neutral temp root with a ``tests`` child.
+
+    The root prefix carries no ``test`` segment, so the module path the check
+    receives is classified as production code rather than a test file.
+    """
+    with tempfile.TemporaryDirectory(prefix="paircov_") as root_name:
+        package_directory = Path(root_name) / "pkg"
+        (package_directory / "tests").mkdir(parents=True)
+        yield package_directory
+
+
+def _write_test_file(package_directory: Path, filename: str, body: str) -> None:
+    (package_directory / "tests" / filename).write_text(body, encoding="utf-8")
+
+
+def test_flags_public_function_absent_from_established_suite(
+    neutral_package_directory: Path,
+) -> None:
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import alpha\n\ndef test_alpha():\n    assert alpha() == 1\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        _TWO_PUBLIC_FUNCTIONS, str(neutral_package_directory / "mod.py")
+    )
+    assert len(all_issues) == 1
+    assert "beta" in all_issues[0]
+    assert "paired test suite" in all_issues[0]
+    assert "alpha" not in all_issues[0]
+
+
+def test_clean_when_suite_covers_every_public_function(
+    neutral_package_directory: Path,
+) -> None:
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import alpha, beta\n\ndef test_both():\n    assert alpha() and beta()\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        _TWO_PUBLIC_FUNCTIONS, str(neutral_package_directory / "mod.py")
+    )
+    assert all_issues == []
+
+
+def test_skips_module_without_dedicated_test_file(
+    neutral_package_directory: Path,
+) -> None:
+    all_issues = check_public_function_missing_paired_test(
+        _TWO_PUBLIC_FUNCTIONS, str(neutral_package_directory / "mod.py")
+    )
+    assert all_issues == []
+
+
+def test_skips_when_suite_covers_no_public_function(
+    neutral_package_directory: Path,
+) -> None:
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "def test_unrelated():\n    assert 1 + 1 == 2\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        _TWO_PUBLIC_FUNCTIONS, str(neutral_package_directory / "mod.py")
+    )
+    assert all_issues == []
+
+
+def test_counts_coverage_across_sibling_test_files(
+    neutral_package_directory: Path,
+) -> None:
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import alpha\n\ndef test_alpha():\n    assert alpha() == 1\n",
+    )
+    _write_test_file(
+        neutral_package_directory,
+        "test_extra.py",
+        "from pkg.mod import beta\n\ndef test_beta():\n    assert beta() == 2\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        _TWO_PUBLIC_FUNCTIONS, str(neutral_package_directory / "mod.py")
+    )
+    assert all_issues == []
+
+
+def test_main_and_private_functions_are_never_required(
+    neutral_package_directory: Path,
+) -> None:
+    module_source = (
+        "def alpha():\n    return 1\n\n\n"
+        "def main():\n    return 0\n\n\n"
+        "def _helper():\n    return 2\n"
+    )
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import alpha\n\ndef test_alpha():\n    assert alpha() == 1\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        module_source, str(neutral_package_directory / "mod.py")
+    )
+    assert all_issues == []
+
+
+def test_exempts_hook_infrastructure_and_test_paths(
+    neutral_package_directory: Path,
+) -> None:
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import alpha\n\ndef test_alpha():\n    assert alpha() == 1\n",
+    )
+    hook_path = "/repo/hooks/blocking/code_rules_paired_test.py"
+    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) == []