claude-dev-env 1.38.1 → 1.40.0

package/hooks/blocking/test_code_rules_enforcer_stub_implementations.py

@@ -0,0 +1,141 @@
+"""Tests for check_stub_implementations — flags placeholder function bodies.
+
+Per Plan 1c.stub_detector / Phase B1: production functions whose body is
+only `pass`, `...` (Ellipsis), or `raise NotImplementedError` are stubs.
+Exemptions: ABC methods, Protocol methods, abstractmethod-decorated
+functions, test files, hook infrastructure.
+"""
+
+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_stub_implementations(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_stub_implementations(content, file_path)
+
+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 test_should_flag_pass_only_function() -> None:
+    source = "def parse_invoice(payload: str) -> int:\n    pass\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert any("parse_invoice" in each for each in issues), (
+        f"Expected pass-only function to be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_ellipsis_only_function() -> None:
+    source = "def parse_invoice(payload: str) -> int:\n    ...\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert any("parse_invoice" in each for each in issues), (
+        f"Expected ellipsis-only function to be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_raise_not_implemented_function() -> None:
+    source = "def parse_invoice(payload: str) -> int:\n    raise NotImplementedError\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert any("parse_invoice" in each for each in issues), (
+        f"Expected NotImplementedError stub to be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_raise_not_implemented_with_message() -> None:
+    source = (
+        "def parse_invoice(payload: str) -> int:\n"
+        "    raise NotImplementedError('coming soon')\n"
+    )
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert any("parse_invoice" in each for each in issues), (
+        f"Expected NotImplementedError(...) stub to be flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_function_with_docstring_then_pass() -> None:
+    source = (
+        "def parse_invoice(payload: str) -> int:\n"
+        '    """Parse the invoice."""\n'
+        "    pass\n"
+    )
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert any("parse_invoice" in each for each in issues), (
+        f"Docstring + pass is still a stub; should be flagged. Got: {issues!r}"
+    )
+
+
+def test_should_not_flag_real_implementation() -> None:
+    source = "def parse_invoice(payload: str) -> int:\n    return len(payload)\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Real impl must not be flagged, got: {issues!r}"
+
+
+def test_should_exempt_abstractmethod_decorated() -> None:
+    source = (
+        "from abc import ABC, abstractmethod\n"
+        "class InvoiceParser(ABC):\n"
+        "    @abstractmethod\n"
+        "    def parse(self, payload: str) -> int:\n"
+        "        pass\n"
+    )
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"@abstractmethod must be exempt, got: {issues!r}"
+
+
+def test_should_exempt_protocol_methods() -> None:
+    source = (
+        "from typing import Protocol\n"
+        "class InvoiceParser(Protocol):\n"
+        "    def parse(self, payload: str) -> int:\n"
+        "        ...\n"
+    )
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Protocol methods must be exempt, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    source = "def stub_helper():\n    pass\n"
+    issues = check_stub_implementations(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files must be exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    source = "def stub_helper():\n    pass\n"
+    issues = check_stub_implementations(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Hook infrastructure must be exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    source = "def parse_invoice(\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax errors must yield no issues, got: {issues!r}"
+
+
+def test_should_include_line_number_in_issue() -> None:
+    source = "x = 1\n\ndef parse_invoice():\n    pass\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "Line 3" in issues[0], f"Issue must include line number, got: {issues[0]!r}"
+
+
+def test_should_cap_at_three_issues() -> None:
+    source = "\n\n".join(f"def stub_{i}():\n    pass" for i in range(5)) + "\n"
+    issues = check_stub_implementations(source, PRODUCTION_FILE_PATH)
+    assert len(issues) <= 3, f"Issue count must be capped at 3, got: {len(issues)}"

package/hooks/blocking/test_code_rules_enforcer_test_branching.py

@@ -0,0 +1,143 @@
+"""Tests for check_test_branching_in_production — flags prod-vs-test branching.
+
+Per Plan 1c.di_pattern_check / Phase B3: production code that branches on
+TESTING / PYTEST_CURRENT_TEST via os.environ creates two parallel
+implementations the wrong way. The correct pattern is dependency injection
+(`_test_hooks.py` sibling) so production code is single-path and tests
+override the dependency.
+"""
+
+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_test_branching_in_production(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_test_branching_in_production(content, file_path)
+
+
+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 test_should_flag_os_environ_get_testing_branch() -> None:
+    source = (
+        "import os\n"
+        "def fetch_user():\n"
+        "    if os.environ.get('TESTING'):\n"
+        "        return None\n"
+        "    return real_fetch()\n"
+    )
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert any("TESTING" in each for each in issues), (
+        f"Expected TESTING env branch flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_pytest_current_test_branch() -> None:
+    source = (
+        "import os\n"
+        "def fetch_user():\n"
+        "    if 'PYTEST_CURRENT_TEST' in os.environ:\n"
+        "        return None\n"
+        "    return real_fetch()\n"
+    )
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert any("PYTEST_CURRENT_TEST" in each for each in issues), (
+        f"Expected PYTEST_CURRENT_TEST branch flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_env_testing_check() -> None:
+    source = (
+        "import os\n"
+        "TESTING_FLAG = os.environ.get('TESTING') == '1'\n"
+        "def get_db():\n"
+        "    if TESTING_FLAG:\n"
+        "        return MockDB()\n"
+        "    return RealDB()\n"
+    )
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert any("TESTING" in each for each in issues), (
+        f"Expected TESTING env access flagged, got: {issues!r}"
+    )
+
+
+def test_should_flag_environ_subscript_testing() -> None:
+    source = (
+        "import os\n"
+        "def get_db():\n"
+        "    if os.environ['TESTING']:\n"
+        "        return None\n"
+        "    return RealDB()\n"
+    )
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert any("TESTING" in each for each in issues), (
+        f"Expected os.environ['TESTING'] flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_other_env_var_access() -> None:
+    source = (
+        "import os\n"
+        "def get_db():\n"
+        "    db_url = os.environ.get('DATABASE_URL')\n"
+        "    return RealDB(db_url)\n"
+    )
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Non-test env vars must not trigger, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    source = (
+        "import os\n"
+        "def fetch_user():\n"
+        "    if os.environ.get('TESTING'):\n"
+        "        return None\n"
+    )
+    issues = check_test_branching_in_production(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    source = (
+        "import os\n"
+        "def fetch_user():\n"
+        "    if os.environ.get('TESTING'):\n"
+        "        return None\n"
+    )
+    issues = check_test_branching_in_production(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    source = "def fetch_user(\n"
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_should_include_line_number_in_issue() -> None:
+    source = (
+        "import os\n\ndef fetch():\n    if os.environ.get('TESTING'):\n        pass\n"
+    )
+    issues = check_test_branching_in_production(source, PRODUCTION_FILE_PATH)
+    assert len(issues) >= 1
+    assert any("Line 4" in each for each in issues), (
+        f"Issue must include line number, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_thin_wrapper_files.py

@@ -0,0 +1,169 @@
+"""Tests for check_thin_wrapper_files — flag re-export-only modules.
+
+Per Plan / Phase B5: a non-`__init__.py` module whose entire body is
+`import` statements plus an `__all__` assignment is a thin wrapper that
+forces callers through an indirection layer with no payload. Callers
+should import from the real module. `__init__.py` is the canonical
+re-export surface and is exempt.
+"""
+
+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_thin_wrapper_files(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_thin_wrapper_files(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/src/aliases.py"
+INIT_FILE_PATH = "/project/src/__init__.py"
+TEST_FILE_PATH = "/project/src/test_aliases.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+CONFIG_FILE_PATH = "/project/config/aliases.py"
+
+
+def test_should_flag_thin_wrapper_with_imports_and_all() -> None:
+    source = (
+        "from real_module import do_thing, other_thing\n"
+        "\n"
+        '__all__ = ["do_thing", "other_thing"]\n'
+    )
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert any("thin wrapper" in each.lower() for each in issues), (
+        f"Expected thin-wrapper flag, got: {issues!r}"
+    )
+
+
+def test_should_flag_thin_wrapper_imports_only_no_all() -> None:
+    source = "from real_module import do_thing\nfrom other_module import other_thing\n"
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert any("thin wrapper" in each.lower() for each in issues), (
+        f"Expected import-only thin-wrapper flag, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_init_file() -> None:
+    source = 'from real_module import do_thing\n\n__all__ = ["do_thing"]\n'
+    issues = check_thin_wrapper_files(source, INIT_FILE_PATH)
+    assert issues == [], (
+        f"__init__.py is the canonical re-export surface, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_file_with_function_definition() -> None:
+    source = (
+        "from real_module import dependency\n"
+        "\n"
+        '__all__ = ["public_helper"]\n'
+        "\n"
+        "def public_helper(value: int) -> int:\n"
+        "    return dependency(value)\n"
+    )
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"File with real code must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_file_with_class_definition() -> None:
+    source = "from real_module import Base\n\nclass Subtype(Base):\n    pass\n"
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"File with class must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_file_with_constant_assignment() -> None:
+    source = (
+        "from real_module import constant_value\n\nDERIVED_VALUE = constant_value * 2\n"
+    )
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"File with derived constant must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    source = "from real_module import do_thing\n\n__all__ = ['do_thing']\n"
+    issues = check_thin_wrapper_files(source, TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    source = "from real_module import do_thing\n\n__all__ = ['do_thing']\n"
+    issues = check_thin_wrapper_files(source, HOOK_INFRASTRUCTURE_PATH)
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_skip_config_file() -> None:
+    source = "from real_module import do_thing\n\n__all__ = ['do_thing']\n"
+    issues = check_thin_wrapper_files(source, CONFIG_FILE_PATH)
+    assert issues == [], f"config/ files exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    source = "from real_module import (\n"
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_should_not_flag_empty_file() -> None:
+    issues = check_thin_wrapper_files("", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Empty file must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_module_docstring_with_real_code() -> None:
+    source = (
+        '"""Module docstring."""\n'
+        "from real_module import dependency\n"
+        "\n"
+        "def helper() -> int:\n"
+        "    return dependency()\n"
+    )
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Docstring + real code must not be flagged, got: {issues!r}"
+
+
+def test_should_flag_thin_wrapper_with_module_docstring() -> None:
+    source = (
+        '"""Module docstring."""\n'
+        "from real_module import do_thing\n"
+        "\n"
+        '__all__ = ["do_thing"]\n'
+    )
+    issues = check_thin_wrapper_files(source, PRODUCTION_FILE_PATH)
+    assert any("thin wrapper" in each.lower() for each in issues), (
+        f"Docstring + import + __all__ is still a thin wrapper, got: {issues!r}"
+    )
+
+
+def test_validate_content_uses_empty_full_file_content_over_pre_edit_fragment() -> None:
+    """An empty-string `full_file_content` must be honored, not silently replaced with `content`.
+
+    Regression for loop1-8: the `or` short-circuit at line 3775 collapsed
+    empty-string and None, so an Edit that produced an empty post-edit file
+    was scanned against the pre-edit fragment instead of the empty file.
+    The thin-wrapper check uses the same idiom — an empty post-edit file is
+    not a thin wrapper, but a pre-edit fragment with imports + __all__ is.
+    """
+    pre_edit_fragment = "from real_module import do_thing\n__all__ = ['do_thing']\n"
+    issues = code_rules_enforcer.validate_content(
+        pre_edit_fragment,
+        PRODUCTION_FILE_PATH,
+        full_file_content="",
+    )
+    assert not any("thin wrapper" in each.lower() for each in issues), (
+        f"empty post-edit file must not be flagged as a thin wrapper, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_todo_markers.py

@@ -0,0 +1,99 @@
+"""Tests covering TODO/FIXME/HACK/XXX exemption from the comment blocker.
+
+CODE_RULES.md requires scaffolding/placeholder code to carry TODO comments
+naming what replaces it and why. Without an exemption, the no-NEW-comments
+rule blocks every authored TODO. These tests pin the exemption.
+"""
+
+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 test_python_check_should_exempt_standalone_todo_comment() -> None:
+    content = "# TODO: replace stub with real implementation\nx = 1\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert issues == [], f"Expected no issues for '# TODO:' but got: {issues!r}"
+
+
+def test_python_check_should_exempt_standalone_fixme_comment() -> None:
+    content = "# FIXME: handle the empty list case\nx = 1\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert issues == [], f"Expected no issues for '# FIXME:' but got: {issues!r}"
+
+
+def test_python_check_should_exempt_standalone_hack_comment() -> None:
+    content = "# HACK: working around upstream bug #1234\nx = 1\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert issues == [], f"Expected no issues for '# HACK:' but got: {issues!r}"
+
+
+def test_python_check_should_exempt_standalone_xxx_comment() -> None:
+    content = "# XXX revisit when API stabilizes\nx = 1\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert issues == [], f"Expected no issues for '# XXX' but got: {issues!r}"
+
+
+def test_python_check_should_exempt_inline_todo_comment() -> None:
+    content = "x = 1  # TODO: extract to config\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert issues == [], f"Expected no issues for inline TODO but got: {issues!r}"
+
+
+def test_python_check_should_exempt_inline_fixme_comment() -> None:
+    content = "x = 1  # FIXME: race condition\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert issues == [], f"Expected no issues for inline FIXME but got: {issues!r}"
+
+
+def test_javascript_check_should_exempt_inline_todo_comment() -> None:
+    content = "const x = 1; // TODO: replace with config\n"
+    issues = code_rules_enforcer.check_comments_javascript(content)
+    assert issues == [], f"Expected no issues for JS inline TODO but got: {issues!r}"
+
+
+def test_javascript_check_should_exempt_inline_fixme_comment() -> None:
+    content = "const x = 1; // FIXME: handle null case\n"
+    issues = code_rules_enforcer.check_comments_javascript(content)
+    assert issues == [], f"Expected no issues for JS inline FIXME but got: {issues!r}"
+
+
+def test_extract_comment_texts_should_skip_standalone_todo() -> None:
+    content = "# TODO: replace stub\nx = 1\n"
+    inline, standalone = code_rules_enforcer.extract_comment_texts(content, "foo.py")
+    assert "# TODO: replace stub" not in standalone, (
+        "Standalone TODO must not be tracked as a comment subject to "
+        f"deletion-blocking, got standalone={standalone!r}"
+    )
+
+
+def test_extract_comment_texts_should_skip_inline_todo() -> None:
+    content = "x = 1  # TODO: extract to config\n"
+    inline, standalone = code_rules_enforcer.extract_comment_texts(content, "foo.py")
+    assert all("TODO" not in each_comment for each_comment in inline), (
+        "Inline TODO must not be tracked as a comment subject to "
+        f"deletion-blocking, got inline={inline!r}"
+    )
+
+
+def test_existing_non_todo_comment_still_flagged() -> None:
+    content = "x = 1  # this is just a comment\n"
+    issues = code_rules_enforcer.check_comments_python(content)
+    assert len(issues) == 1, (
+        f"Expected non-TODO inline comment to still be flagged, got: {issues!r}"
+    )