claude-dev-env 1.49.1 → 1.50.1

package/hooks/blocking/test_code_rules_enforcer_docstring_args_signature.py

@@ -0,0 +1,256 @@
+"""Tests for check_docstring_args_match_signature — Args:-vs-signature drift.
+
+A documented ``Args:`` entry naming a parameter the signature lacks is the
+stale residue of a rename. Only the ``Args:`` section is validated; ``Raises:``
+is left alone because callee-propagated exceptions cause false positives.
+"""
+
+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_args_match_signature(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_args_match_signature(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/services.py"
+TEST_FILE_PATH = "/project/src/test_services.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _function_with_stale_arg() -> str:
+    return (
+        "def fetch_user(account_id: int) -> str:\n"
+        '    """Look up a user by id.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id: The user identifier.\n"
+        "\n"
+        "    Returns:\n"
+        "        The user name.\n"
+        '    """\n'
+        "    lookup = _registry.get(account_id)\n"
+        "    if not lookup:\n"
+        "        return ''\n"
+        "    return lookup.name\n"
+    )
+
+
+def test_should_flag_documented_arg_not_in_signature() -> None:
+    issues = check_docstring_args_match_signature(_function_with_stale_arg(), PRODUCTION_FILE_PATH)
+    assert any("user_id" in each for each in issues), (
+        f"Expected stale 'user_id' flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_when_args_match_signature() -> None:
+    source = (
+        "def fetch_user(user_id: int) -> str:\n"
+        '    """Look up a user by id.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id: The user identifier.\n"
+        "\n"
+        "    Returns:\n"
+        "        The user name.\n"
+        '    """\n'
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        return ''\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Matching Args must not be flagged, got: {issues!r}"
+
+
+def test_should_handle_parenthesized_type_in_arg_entry() -> None:
+    source = (
+        "def fetch_user(account_id: int) -> str:\n"
+        '    """Look up a user by id.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id (int): The user identifier.\n"
+        "\n"
+        "    Returns:\n"
+        "        The user name.\n"
+        '    """\n'
+        "    lookup = _registry.get(account_id)\n"
+        "    if not lookup:\n"
+        "        return ''\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert any("user_id" in each for each in issues), (
+        f"Parenthesized-type entry must still be parsed, got: {issues!r}"
+    )
+
+
+def test_should_count_vararg_and_kwarg_as_real_parameters() -> None:
+    source = (
+        "def collect(first: int, *extra_values, **options) -> int:\n"
+        '    """Collect values.\n'
+        "\n"
+        "    Args:\n"
+        "        first: The leading value.\n"
+        "        extra_values: Additional positional values.\n"
+        "        options: Keyword overrides.\n"
+        '    """\n'
+        "    total = first\n"
+        "    for each_value in extra_values:\n"
+        "        total += each_value\n"
+        "    return total\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"vararg/kwarg must count as parameters, got: {issues!r}"
+
+
+def test_should_not_flag_self_documented_when_method_uses_self() -> None:
+    source = (
+        "class Service:\n"
+        "    def fetch(self, user_id: int) -> int:\n"
+        '        """Fetch a record.\n'
+        "\n"
+        "        Args:\n"
+        "            user_id: The user identifier.\n"
+        '        """\n'
+        "        record = self._registry.get(user_id)\n"
+        "        if record is None:\n"
+        "            return 0\n"
+        "        return record\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"self-using method must not be flagged, got: {issues!r}"
+
+
+def test_should_stop_parsing_args_at_next_section() -> None:
+    source = (
+        "def fetch_user(user_id: int) -> str:\n"
+        '    """Look up a user by id.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id: The user identifier.\n"
+        "\n"
+        "    Raises:\n"
+        "        LookupError: When missing.\n"
+        '    """\n'
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        raise LookupError('missing')\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Raises entries past Args must be ignored, got: {issues!r}"
+
+
+def test_should_skip_private_function() -> None:
+    source = (
+        "def _fetch(account_id: int) -> int:\n"
+        '    """Fetch internally.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id: stale name.\n"
+        '    """\n'
+        "    value = _registry.get(account_id)\n"
+        "    return value\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private functions exempt, got: {issues!r}"
+
+
+def test_should_skip_short_function() -> None:
+    source = (
+        "def fetch(account_id: int) -> int:\n"
+        '    """Args:\n'
+        "        user_id: stale.\n"
+        '    """\n'
+        "    return account_id\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Trivial-body functions exempt, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_args_match_signature(_function_with_stale_arg(), TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_args_match_signature(
+        _function_with_stale_arg(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_args_match_signature("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_args_drift() -> None:
+    issues = validate_content(_function_with_stale_arg(), PRODUCTION_FILE_PATH, old_content="")
+    matching_issues = [each for each in issues if "user_id" in each and "Args" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the Args drift issue, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_deeper_indented_continuation_line() -> None:
+    source = (
+        "def fetch_user(user_id: int) -> str:\n"
+        '    """Look up a user by id.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id: The user identifier. Example mapping:\n"
+        "            shadow_key: not a parameter.\n"
+        "\n"
+        "    Returns:\n"
+        "        The user name.\n"
+        '    """\n'
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        return ''\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Continuation lines must not be parsed as args, got: {issues!r}"
+
+
+def test_should_not_flag_documented_kwargs_keys() -> None:
+    source = (
+        "def configure(timeout: int, **overrides) -> None:\n"
+        '    """Configure the client.\n'
+        "\n"
+        "    Args:\n"
+        "        timeout: Seconds to wait.\n"
+        "        max_retries: A documented keyword override.\n"
+        "\n"
+        "    Returns:\n"
+        "        None.\n"
+        '    """\n'
+        "    settings = dict(overrides)\n"
+        "    settings['timeout'] = timeout\n"
+        "    return None\n"
+    )
+    issues = check_docstring_args_match_signature(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"**kwargs-key docs must not be flagged, got: {issues!r}"

package/hooks/blocking/test_code_rules_enforcer_function_length.py

@@ -1,10 +1,15 @@
 """Tests for ``check_function_length``.
 
-Functions whose definition span (signature line through last body statement,
-inclusive) is at or above ``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60) block the
-write (small-function basis: Robert C. Martin, Clean Code Ch. 3 "Functions";
-Google Python Style Guide ~40-line function review hint). Spans below the
-threshold pass silently.
+Functions whose executable span (signature line through last body statement,
+inclusive, minus the leading docstring lines of the function and of every
+function or class nested within it) is at or above
+``FUNCTION_LENGTH_BLOCKING_THRESHOLD`` (60) block the write (small-function
+basis: Robert C. Martin, Clean Code Ch. 3 "Functions"; Google Python Style
+Guide ~40-line function review hint — a measure of executable complexity,
+paired with the Guide's complete-docstring mandate for public APIs). Executable
+spans below the threshold pass silently, whatever the docstring adds to the
+full declared span; the issue message keeps reporting the full declared span so
+the commit gate's span recovery holds.
 
 Cited SYNTHESIS evidence: pa#143 F4, F9, F14 (three recurrences in one PR);
 pa#136 F20.
@@ -208,3 +213,129 @@ def test_reports_only_in_scope_violation_among_untouched_ones() -> None:
     )
     assert any("target_function" in each_issue for each_issue in issues)
     assert not any("leading_" in each_issue for each_issue in issues)
+
+
+def _build_docstring_function_source(
+    name: str, docstring_line_count: int, body_line_count: int
+) -> str:
+    """Build a function whose leading docstring spans ``docstring_line_count + 2``
+    source lines (opening summary line, the counted filler lines, closing quotes)
+    followed by ``body_line_count`` executable statements."""
+    docstring_lines = [
+        '    """Documented helper.',
+        *(
+            f"    documentation line {each_index}."
+            for each_index in range(docstring_line_count)
+        ),
+        '    """',
+    ]
+    all_source_lines = [
+        f"def {name}() -> None:",
+        *docstring_lines,
+        *(
+            f"    statement_{each_index} = {each_index}"
+            for each_index in range(body_line_count)
+        ),
+    ]
+    return "\n".join(all_source_lines) + "\n"
+
+
+def test_docstring_heavy_function_with_small_body_passes() -> None:
+    """A complete Google-style docstring must not push a small-bodied function
+    over the gate: the threshold measures executable lines only."""
+    source = _build_docstring_function_source(
+        "documented_compact_helper",
+        docstring_line_count=hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD,
+        body_line_count=5,
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"docstring lines must not count toward the gate, got: {issues!r}"
+
+
+def test_oversized_executable_body_blocks_despite_docstring() -> None:
+    """A docstring does not acquit a genuinely large executable body, and the
+    issue message reports the full declared span so the commit gate's
+    ``function_length_span_range`` recovery keeps covering the whole function."""
+    docstring_line_count = 10
+    body_line_count = hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD - 1
+    source = _build_docstring_function_source(
+        "documented_oversized_helper",
+        docstring_line_count=docstring_line_count,
+        body_line_count=body_line_count,
+    )
+    full_declared_span = 1 + (docstring_line_count + 2) + body_line_count
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert any("documented_oversized_helper" in each_issue for each_issue in issues)
+    assert any(f"is {full_declared_span} lines" in each_issue for each_issue in issues)
+
+
+def test_executable_span_boundary_sits_one_below_threshold() -> None:
+    """With the docstring excluded, an executable span of THRESHOLD - 1 passes
+    even though the full declared span sits far above the threshold."""
+    source = _build_docstring_function_source(
+        "documented_boundary_helper",
+        docstring_line_count=20,
+        body_line_count=hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD - 2,
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_builder_zero_docstring_line_count_keeps_span_contract() -> None:
+    """The builder's docstring-span contract (``docstring_line_count + 2``) holds
+    at the zero boundary, so hand-computed span oracles in tests cannot drift."""
+    source = _build_docstring_function_source(
+        "documented_minimal_helper", docstring_line_count=0, body_line_count=3
+    )
+    expected_total_lines = 1 + (0 + 2) + 3
+    assert len(source.splitlines()) == expected_total_lines
+
+
+def test_builder_zero_body_line_count_keeps_span_contract() -> None:
+    """The builder's span contract holds at the zero-body boundary, so a
+    docstring-only function's hand-computed span oracle cannot drift."""
+    source = _build_docstring_function_source(
+        "documented_bodyless_helper", docstring_line_count=5, body_line_count=0
+    )
+    expected_total_lines = 1 + (5 + 2) + 0
+    assert len(source.splitlines()) == expected_total_lines
+
+
+def test_nested_function_docstring_does_not_count_toward_outer() -> None:
+    """A nested helper's docstring is documentation too: the outer function's
+    executable span excludes every leading docstring within its declared span."""
+    nested_docstring_filler = "\n".join(
+        f"        nested documentation line {each_index}."
+        for each_index in range(hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD)
+    )
+    source = (
+        "def outer_documented_orchestrator() -> None:\n"
+        "    def nested_documented_helper() -> None:\n"
+        '        """Documented nested helper.\n'
+        f"{nested_docstring_filler}\n"
+        '        """\n'
+        "        nested_statement = 1\n"
+        "    outer_statement = 2\n"
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"nested docstring lines must not count toward the gate, got: {issues!r}"
+
+
+def test_nested_class_docstring_does_not_count_toward_outer() -> None:
+    """A nested class's docstring is documentation too: the outer function's
+    executable span excludes leading docstrings of nested classes as well."""
+    nested_class_docstring_filler = "\n".join(
+        f"        nested class documentation line {each_index}."
+        for each_index in range(hook_module.FUNCTION_LENGTH_BLOCKING_THRESHOLD)
+    )
+    source = (
+        "def outer_class_documented_orchestrator() -> None:\n"
+        "    class NestedDocumentedConfig:\n"
+        '        """Documented nested class.\n'
+        f"{nested_class_docstring_filler}\n"
+        '        """\n'
+        "        nested_field = 1\n"
+        "    outer_statement = 2\n"
+    )
+    issues = check_function_length(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"nested class docstring lines must not count toward the gate, got: {issues!r}"

package/hooks/blocking/test_code_rules_enforcer_ignored_must_check_return.py

@@ -0,0 +1,256 @@
+"""Tests for check_ignored_must_check_return — discarded must-check outcomes.
+
+A bare-statement call to a function in ALL_MUST_CHECK_RETURN_FUNCTION_NAMES
+discards the only failure signal it produces. An assigned or branched-on
+call is exempt; only bare ``ast.Expr`` calls are flagged.
+"""
+
+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_ignored_must_check_return(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_ignored_must_check_return(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/clicker.py"
+TEST_FILE_PATH = "/project/src/test_clicker.py"
+
+
+def test_should_flag_bare_find_and_click_call() -> None:
+    source = "def step() -> None:\n    find_and_click('#submit')\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert any("find_and_click" in each for each in issues), (
+        f"Expected discarded-return flag for find_and_click, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_flag_bare_write_outcome_call() -> None:
+    source = "def step() -> None:\n    write_outcome('done')\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert any("write_outcome" in each for each in issues), (
+        f"Expected discarded-return flag for write_outcome, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_flag_attribute_call_with_must_check_name() -> None:
+    source = "def step() -> None:\n    self.find_and_click('#submit')\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1, f"Attribute call terminal name must be resolved, got: {issues!r}"
+
+
+def test_should_not_flag_assigned_find_and_click() -> None:
+    source = "def step() -> None:\n    clicked = find_and_click('#submit')\n    print(clicked)\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Assigned call must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_branched_find_and_click() -> None:
+    source = "def step() -> None:\n    if find_and_click('#submit'):\n        pass\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Branched-on call must not be flagged, got: {issues!r}"
+
+
+def test_should_flag_bare_awaited_find_and_click_call() -> None:
+    source = "async def step() -> None:\n    await find_and_click('#x')\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert any("find_and_click" in each for each in issues), (
+        f"Expected discarded-return flag for awaited find_and_click, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_assigned_awaited_find_and_click() -> None:
+    source = (
+        "async def step() -> None:\n"
+        "    clicked = await find_and_click('#x')\n"
+        "    print(clicked)\n"
+    )
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Assigned awaited call must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_branched_awaited_find_and_click() -> None:
+    source = "async def step() -> None:\n    if await find_and_click('#x'):\n        pass\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Branched-on awaited call must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_unrelated_bare_call() -> None:
+    source = "def step() -> None:\n    print('hello')\n"
+    issues = check_ignored_must_check_return(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Unrelated call must not be flagged, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    source = "def step() -> None:\n    find_and_click('#submit')\n"
+    issues = check_ignored_must_check_return(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_ignored_must_check_return("def step(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_discarded_return() -> None:
+    source = "def step() -> None:\n    find_and_click('#submit')\n"
+    issues = validate_content(source, PRODUCTION_FILE_PATH, old_content="")
+    matching_issues = [each for each in issues if "find_and_click" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the discarded-return issue, got: {issues!r}"
+    )
+
+
+EDIT_FULL_MODULE_SOURCE = (
+    "async def step() -> None:\n"
+    "    await find_and_click('#x')\n"
+)
+AWAITED_CALL_LINE_NUMBER = 2
+UNCHANGED_LINE_NUMBER = 1
+
+
+def test_should_flag_when_changed_line_covers_the_bare_await() -> None:
+    all_changed_lines = {AWAITED_CALL_LINE_NUMBER}
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        EDIT_FULL_MODULE_SOURCE,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines,
+        False,
+    )
+    assert len(issues) == 1, (
+        f"An Edit touching the bare await line must surface exactly one issue, got: {issues!r}"
+    )
+    assert "find_and_click" in issues[0]
+
+
+def test_should_not_flag_when_changed_line_excludes_the_bare_await() -> None:
+    all_changed_lines = {UNCHANGED_LINE_NUMBER}
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        EDIT_FULL_MODULE_SOURCE,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines,
+        False,
+    )
+    assert issues == [], (
+        f"A pre-existing violation on an unedited line must not block the edit, got: {issues!r}"
+    )
+
+
+PRE_EXISTING_BARE_CALL_COUNT = 5
+EDITED_BARE_CALL_LINE_NUMBER = PRE_EXISTING_BARE_CALL_COUNT + 2
+
+
+def _build_module_with_pre_existing_violations_before_the_edit() -> str:
+    all_signature_lines = ["async def step() -> None:"]
+    all_pre_existing_call_lines = [
+        f"    await find_and_click('#x{each_index}')"
+        for each_index in range(PRE_EXISTING_BARE_CALL_COUNT)
+    ]
+    edited_call_line = "    await find_and_click('#edited')"
+    all_lines = all_signature_lines + all_pre_existing_call_lines + [edited_call_line]
+    return "\n".join(all_lines) + "\n"
+
+
+def test_should_flag_edited_line_even_when_cap_worth_of_violations_precede_it() -> None:
+    source = _build_module_with_pre_existing_violations_before_the_edit()
+    all_changed_lines = {EDITED_BARE_CALL_LINE_NUMBER}
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines,
+        False,
+    )
+    assert len(issues) == 1, (
+        "Collecting every violation before scoping must surface the edited-line "
+        f"violation even with a cap's worth of earlier out-of-scope calls, got: {issues!r}"
+    )
+    assert f"Line {EDITED_BARE_CALL_LINE_NUMBER}:" in issues[0], (
+        f"The single issue must name the edited line {EDITED_BARE_CALL_LINE_NUMBER}, got: {issues!r}"
+    )
+
+
+def _build_module_with_more_than_cap_bare_calls() -> tuple[str, int]:
+    bare_call_count = code_rules_enforcer.MAX_IGNORED_MUST_CHECK_RETURN_ISSUES + 3
+    all_signature_lines = ["async def step() -> None:"]
+    all_call_lines = [
+        f"    await find_and_click('#x{each_index}')"
+        for each_index in range(bare_call_count)
+    ]
+    source = "\n".join(all_signature_lines + all_call_lines) + "\n"
+    return source, bare_call_count
+
+
+def test_deferred_scope_returns_every_violation_uncapped() -> None:
+    source, bare_call_count = _build_module_with_more_than_cap_bare_calls()
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source,
+        PRODUCTION_FILE_PATH,
+        None,
+        True,
+    )
+    assert len(issues) == bare_call_count, (
+        "With defer_scope_to_caller=True the gate must see every violation uncapped "
+        f"so it can scope by added line, got: {issues!r}"
+    )
+
+
+def test_terminal_scope_caps_violations_at_the_module_limit() -> None:
+    source, _ = _build_module_with_more_than_cap_bare_calls()
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source,
+        PRODUCTION_FILE_PATH,
+        None,
+        False,
+    )
+    assert len(issues) == code_rules_enforcer.MAX_IGNORED_MUST_CHECK_RETURN_ISSUES, (
+        "The terminal hook path with all_changed_lines=None must cap at the module "
+        f"limit, got: {issues!r}"
+    )
+
+
+WRAPPED_CALL_OPEN_PAREN_LINE_NUMBER = 2
+WRAPPED_CALL_ARGUMENT_LINE_NUMBER = 3
+
+
+def test_should_flag_when_changed_line_covers_a_later_line_of_a_wrapped_call() -> None:
+    source = (
+        "def step() -> None:\n"
+        "    find_and_click(\n"
+        "        '#submit',\n"
+        "    )\n"
+    )
+    all_changed_lines = {WRAPPED_CALL_ARGUMENT_LINE_NUMBER}
+    issues = code_rules_enforcer.check_ignored_must_check_return(
+        source,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines,
+        False,
+    )
+    assert len(issues) == 1, (
+        "Editing a later line of a multi-line bare must-check call must still flag it "
+        f"because the violation span covers the whole call, got: {issues!r}"
+    )
+    assert "find_and_click" in issues[0]