claude-dev-env 1.49.1 → 1.50.0

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_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]

package/hooks/blocking/test_code_rules_enforcer_naming_pattern.py

@@ -26,7 +26,7 @@ TEST_FILE_PATH = "src/app/test_feature.py"
 CONFIG_FILE_PATH = "src/config/settings.py"
 WORKFLOW_FILE_PATH = "src/workflow/orders_tab.py"
 HOOK_FILE_PATH = "/home/user/.claude/hooks/blocking/my_hook.py"
-EXPECTED_PREFIX_GUIDANCE = "prefix with is_/has_/should_/can_"
+EXPECTED_PREFIX_GUIDANCE = "prefix with is_/has_/should_/can_/was_/did_"
 
 
 def _assert_flags_name(issues: list[str], name: str, line_number: int) -> None:
@@ -210,3 +210,139 @@ def test_should_allow_is_prefix_at_start_when_compound_word_follows() -> None:
     assert issues == [], (
         f"is_left_upper_snake has prefix at position 0, must pass, got: {issues}"
     )
+
+
+PARAMETER_PREFIX_GUIDANCE = "prefix with is_/has_/should_/can_/was_/did_"
+
+
+def _assert_flags_parameter(issues: list[str], name: str, line_number: int) -> None:
+    expected = f"Line {line_number}: Boolean parameter {name} - {PARAMETER_PREFIX_GUIDANCE}"
+    assert expected in issues, f"expected {expected!r} in {issues!r}"
+
+
+def test_should_flag_bool_annotated_parameter_without_prefix() -> None:
+    source = "def run(dry_run: bool) -> None:\n    print(dry_run)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "dry_run", 1)
+    assert len(issues) == 1
+
+
+def test_should_flag_bool_default_parameter_without_annotation() -> None:
+    source = "def run(apply_historical_weight=False) -> None:\n    print(apply_historical_weight)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "apply_historical_weight", 1)
+    assert len(issues) == 1
+
+
+def test_should_flag_keyword_only_bool_parameter_without_prefix() -> None:
+    source = "def run(*, click_succeeded: bool = True) -> None:\n    print(click_succeeded)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "click_succeeded", 1)
+    assert len(issues) == 1
+
+
+def test_should_allow_is_prefixed_bool_parameter() -> None:
+    source = "def run(is_dry_run: bool) -> None:\n    print(is_dry_run)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_was_prefixed_bool_parameter() -> None:
+    source = "def run(was_clicked: bool = False) -> None:\n    print(was_clicked)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_did_prefixed_bool_parameter() -> None:
+    source = "def run(did_succeed: bool) -> None:\n    print(did_succeed)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_was_prefixed_bool_assignment() -> None:
+    source = "def f() -> None:\n    was_clicked = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_did_prefixed_bool_assignment() -> None:
+    source = "def f() -> None:\n    did_run = False\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_single_letter_bool_parameter() -> None:
+    source = "def run(x: bool) -> None:\n    print(x)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_self_parameter_in_method() -> None:
+    source = (
+        "class Runner:\n"
+        "    def run(self, enabled: bool) -> None:\n"
+        "        print(self, enabled)\n"
+    )
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "enabled", 2)
+    assert len(issues) == 1
+
+
+def test_should_not_flag_non_bool_parameter() -> None:
+    source = "def run(retries: int) -> None:\n    print(retries)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_bool_parameter_in_test_file() -> None:
+    source = "def run(dry_run: bool) -> None:\n    print(dry_run)\n"
+    issues = check_boolean_naming(source, TEST_FILE_PATH)
+    assert issues == []
+
+
+def test_should_pair_positional_defaults_right_aligned() -> None:
+    source = (
+        "def run(name: str, verbose: bool = False) -> None:\n"
+        "    print(name, verbose)\n"
+    )
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "verbose", 1)
+    assert len(issues) == 1
+
+
+FULL_MODULE_WITH_TWO_UNPREFIXED_BOOL_PARAMETERS = (
+    "def pre_existing(verbose: bool) -> None:\n"
+    "    print(verbose)\n"
+    "\n\n"
+    "def edited(detailed: bool) -> None:\n"
+    "    print(detailed)\n"
+)
+PRE_EXISTING_BOOL_PARAMETER_LINE_NUMBER = 1
+EDITED_BOOL_PARAMETER_LINE_NUMBER = 5
+
+
+def test_should_flag_bool_parameter_on_changed_line() -> None:
+    issues = check_boolean_naming(
+        FULL_MODULE_WITH_TWO_UNPREFIXED_BOOL_PARAMETERS,
+        PRODUCTION_FILE_PATH,
+        {EDITED_BOOL_PARAMETER_LINE_NUMBER},
+        False,
+    )
+    _assert_flags_parameter(issues, "detailed", EDITED_BOOL_PARAMETER_LINE_NUMBER)
+    assert len(issues) == 1, (
+        "Only the bool parameter on the changed line must be flagged, got: "
+        f"{issues!r}"
+    )
+
+
+def test_should_not_flag_pre_existing_bool_parameter_on_unchanged_line() -> None:
+    issues = check_boolean_naming(
+        FULL_MODULE_WITH_TWO_UNPREFIXED_BOOL_PARAMETERS,
+        PRODUCTION_FILE_PATH,
+        {EDITED_BOOL_PARAMETER_LINE_NUMBER},
+        False,
+    )
+    assert not any("verbose" in each_issue for each_issue in issues), (
+        "A pre-existing unprefixed bool parameter on an unedited line must not block "
+        f"the edit, got: {issues!r}"
+    )