claude-dev-env 1.77.0 → 1.79.0

package/hooks/blocking/test_code_rules_enforcer_docstring_unreferenced_param.py

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

package/hooks/blocking/test_code_rules_enforcer_module_docstring_data_schema_scope.py

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

package/hooks/blocking/test_code_rules_enforcer_paired_test.py

@@ -0,0 +1,339 @@
+"""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,
+    check_test_file_omits_module_public_function,
+)
+
+_TWO_PUBLIC_FUNCTIONS = "def alpha():\n    return 1\n\n\ndef beta():\n    return 2\n"
+_THREE_PUBLIC_FUNCTIONS = (
+    "def alpha():\n    return 1\n\n\n"
+    "def beta():\n    return 2\n\n\n"
+    "def gamma():\n    return 3\n"
+)
+
+
+@pytest.fixture
+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_flags_public_surface_when_suite_exercises_only_private_helper(
+    neutral_package_directory: Path,
+) -> None:
+    module_source = (
+        "def _aarrggbb_to_css(value):\n    return value\n\n\n"
+        "def render_table():\n    return _aarrggbb_to_css('x')\n\n\n"
+        "def render_summary():\n    return 2\n"
+    )
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        "from pkg.mod import _aarrggbb_to_css\n\n"
+        "def test_helper():\n    assert _aarrggbb_to_css('x') == 'x'\n",
+    )
+    all_issues = check_public_function_missing_paired_test(
+        module_source, str(neutral_package_directory / "mod.py")
+    )
+    assert len(all_issues) == 2
+    flagged_names = " ".join(all_issues)
+    assert "render_table" in flagged_names
+    assert "render_summary" in flagged_names
+
+
+def test_counts_coverage_across_sibling_test_files(
+    neutral_package_directory: Path,
+) -> None:
+    _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) == []
+
+
+def _write_module(package_directory: Path, body: str) -> None:
+    (package_directory / "mod.py").write_text(body, encoding="utf-8")
+
+
+_SUITE_COVERS_ALPHA_BETA = (
+    "from pkg.mod import alpha, beta\n\n"
+    "def test_pair():\n    assert alpha() == 1 and beta() == 2\n"
+)
+
+
+def test_flags_module_public_function_when_test_suite_omits_it(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert len(all_issues) == 1
+    assert "gamma" in all_issues[0]
+    assert "mod.py" in all_issues[0]
+    assert "alpha" not in all_issues[0]
+    assert "beta" not in all_issues[0]
+
+
+def test_clean_when_test_suite_covers_every_module_public_function(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    suite_covers_all = (
+        "from pkg.mod import alpha, beta, gamma\n\n"
+        "def test_all():\n    assert alpha() and beta() and gamma()\n"
+    )
+    all_issues = check_test_file_omits_module_public_function(suite_covers_all, test_path)
+    assert all_issues == []
+
+
+def test_skips_when_test_suite_covers_no_module_public_function(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        "def test_unrelated():\n    assert 1 + 1 == 2\n", test_path
+    )
+    assert all_issues == []
+
+
+def test_skips_test_file_with_no_paired_production_module(
+    neutral_package_directory: Path,
+) -> None:
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert all_issues == []
+
+
+def test_ignores_a_non_stem_matched_written_file(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    helper_path = str(neutral_package_directory / "helper.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, helper_path
+    )
+    assert all_issues == []
+
+
+def test_resolves_production_module_beside_the_test_file(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    beside_test_path = str(neutral_package_directory / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, beside_test_path
+    )
+    assert len(all_issues) == 1
+    assert "gamma" in all_issues[0]
+
+
+def test_judges_post_edit_content_over_stale_on_disk_test(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    _write_test_file(
+        neutral_package_directory,
+        "test_mod.py",
+        _SUITE_COVERS_ALPHA_BETA,
+    )
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    post_edit_covers_all = (
+        "from pkg.mod import alpha, beta, gamma\n\n"
+        "def test_all():\n    assert alpha() and beta() and gamma()\n"
+    )
+    all_issues = check_test_file_omits_module_public_function(
+        post_edit_covers_all, test_path
+    )
+    assert all_issues == []
+
+
+def test_counts_coverage_across_sibling_test_files_on_test_write(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    _write_test_file(
+        neutral_package_directory,
+        "test_extra.py",
+        "from pkg.mod import gamma\n\ndef test_gamma():\n    assert gamma() == 3\n",
+    )
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert all_issues == []
+
+
+def test_test_side_message_names_module_and_function_without_line_prefix(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert len(all_issues) == 1
+    assert not all_issues[0].startswith("Line ")
+    assert "mod.py" in all_issues[0]
+    assert "gamma" in all_issues[0]
+
+
+def test_test_side_omission_blocks_on_any_test_file_edit(
+    neutral_package_directory: Path,
+) -> None:
+    _write_module(neutral_package_directory, _THREE_PUBLIC_FUNCTIONS)
+    test_path = str(neutral_package_directory / "tests" / "test_mod.py")
+    all_issues = check_test_file_omits_module_public_function(
+        _SUITE_COVERS_ALPHA_BETA, test_path
+    )
+    assert len(all_issues) == 1
+    assert "gamma" in all_issues[0]
+
+
+def test_skips_when_paired_production_module_is_exempt(
+    neutral_package_directory: Path,
+) -> None:
+    (neutral_package_directory / "__init__.py").write_text(
+        _THREE_PUBLIC_FUNCTIONS, encoding="utf-8"
+    )
+    beside_test_path = str(neutral_package_directory / "test___init__.py")
+    suite_covers_all = (
+        "from pkg import alpha, beta, gamma\n\n"
+        "def test_all():\n    assert alpha() and beta() and gamma()\n"
+    )
+    all_issues = check_test_file_omits_module_public_function(
+        suite_covers_all, beside_test_path
+    )
+    assert all_issues == []

package/hooks/blocking/test_code_rules_enforcer_polarity_name_contradiction.py

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