claude-dev-env 1.38.0 → 1.39.0

package/hooks/blocking/test_code_rules_enforcer_collection_prefix.py

@@ -76,6 +76,56 @@ def test_should_flag_pep604_union_dict_parameter() -> None:
     )
 
 
+def test_should_not_flag_bare_dict_parameter() -> None:
+    source = "def consume(user_record: dict) -> None:\n    return None\n"
+    issues = code_rules_enforcer.check_collection_prefix(source, PRODUCTION_FILE_PATH)
+    assert not any(
+        "Collection parameter user_record -" in each_issue for each_issue in issues
+    ), (
+        f"Bare dict parameter is a structured record, not a collection, got: {issues}"
+    )
+
+
+def test_should_flag_subscripted_dict_parameter() -> None:
+    source = "def consume(price_lookup: dict[str, int]) -> None:\n    return None\n"
+    issues = code_rules_enforcer.check_collection_prefix(source, PRODUCTION_FILE_PATH)
+    assert any(
+        "Collection parameter price_lookup -" in each_issue for each_issue in issues
+    ), (
+        f"Expected dict[K, V] parameter flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_module_level_bare_dict_constant() -> None:
+    source = "MY_USER_RECORD: dict = {}\n"
+    issues = code_rules_enforcer.check_collection_prefix(source, PRODUCTION_FILE_PATH)
+    assert not any(
+        "Collection constant MY_USER_RECORD -" in each_issue for each_issue in issues
+    ), (
+        f"Bare dict module-level constant is a structured record, not a collection, got: {issues}"
+    )
+
+
+def test_should_flag_module_level_subscripted_dict_constant_without_all_prefix() -> None:
+    source = "MY_PRICE_LOOKUP: dict[str, int] = {}\n"
+    issues = code_rules_enforcer.check_collection_prefix(source, PRODUCTION_FILE_PATH)
+    assert any(
+        "Collection constant MY_PRICE_LOOKUP -" in each_issue for each_issue in issues
+    ), (
+        f"Expected dict[K, V] module-level constant flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_pep604_bare_dict_union_parameter() -> None:
+    source = "def consume(user_record: dict | None = None) -> None:\n    return None\n"
+    issues = code_rules_enforcer.check_collection_prefix(source, PRODUCTION_FILE_PATH)
+    assert not any(
+        "Collection parameter user_record -" in each_issue for each_issue in issues
+    ), (
+        f"Bare dict | None parameter is a structured record, not a collection, got: {issues}"
+    )
+
+
 def test_should_not_flag_pep604_union_when_param_has_all_prefix() -> None:
     source = (
         "def consume(all_numbers: set[int] | None = None) -> None:\n    return None\n"

package/hooks/blocking/test_code_rules_enforcer_docstring_format.py

@@ -0,0 +1,255 @@
+"""Tests for check_docstring_format — Google-style Args:/Returns:/Raises:.
+
+Per Plan 1c.docstring_format_check / Phase B7: a public function whose
+signature takes parameters, returns a non-None value, or raises an
+exception must document those facts in Google-style sections so
+callers can reason about the contract without reading the body.
+
+Exemptions: private (`_foo`), dunder (`__init__`), `@property`,
+functions ≤3 lines (trivial), abstract methods, test files.
+"""
+
+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_format(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_format(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 _function_with_param_no_docstring() -> str:
+    return (
+        "def fetch_user(user_id: int) -> str:\n"
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        return ''\n"
+        "    return lookup.name\n"
+    )
+
+
+def test_should_flag_public_function_with_params_missing_args_section() -> None:
+    issues = check_docstring_format(
+        _function_with_param_no_docstring(), PRODUCTION_FILE_PATH
+    )
+    assert any("Args" in each for each in issues), (
+        f"Expected missing-Args flag, got: {issues!r}"
+    )
+
+
+def test_should_flag_public_function_with_non_none_return_missing_returns_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'
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        return ''\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert any("Returns" in each or "Yields" in each for each in issues), (
+        f"Expected missing-Returns flag, got: {issues!r}"
+    )
+
+
+def test_should_flag_public_function_with_raise_missing_raises_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"
+        "    Returns:\n"
+        "        The user name.\n"
+        '    """\n'
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        raise LookupError('missing')\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert any("Raises" in each for each in issues), (
+        f"Expected missing-Raises flag, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_function_with_complete_google_docstring() -> 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"
+        "    Raises:\n"
+        "        LookupError: When the user is missing.\n"
+        '    """\n'
+        "    lookup = _registry.get(user_id)\n"
+        "    if not lookup:\n"
+        "        raise LookupError('missing')\n"
+        "    return lookup.name\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Complete docstring must not be flagged, got: {issues!r}"
+
+
+def test_should_not_require_returns_when_return_type_is_none() -> None:
+    source = (
+        "def store_user(user_id: int) -> None:\n"
+        '    """Persist a user record.\n'
+        "\n"
+        "    Args:\n"
+        "        user_id: The user identifier.\n"
+        '    """\n'
+        "    if user_id < 0:\n"
+        "        return\n"
+        "    _registry[user_id] = True\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"None-returning function must not require Returns:, got: {issues!r}"
+    )
+
+
+def test_should_accept_yields_in_lieu_of_returns_for_generator() -> None:
+    source = (
+        'def stream_users(batch_size: int) -> "Iterator[str]":\n'
+        '    """Stream user names lazily.\n'
+        "\n"
+        "    Args:\n"
+        "        batch_size: How many to read at a time.\n"
+        "\n"
+        "    Yields:\n"
+        "        Each user name in turn.\n"
+        '    """\n'
+        "    for each in _registry.values():\n"
+        "        yield each.name\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Yields: must satisfy Returns: requirement, got: {issues!r}"
+
+
+def test_should_skip_private_function() -> None:
+    source = "def _internal_helper(value: int) -> int:\n    return value * 2\n"
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private functions exempt, got: {issues!r}"
+
+
+def test_should_skip_dunder_method() -> None:
+    source = (
+        "class Cache:\n"
+        "    def __init__(self, capacity: int) -> None:\n"
+        "        self._capacity = capacity\n"
+        "        self._storage = {}\n"
+        "        self._hits = 0\n"
+        "        self._misses = 0\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Dunder methods exempt, got: {issues!r}"
+
+
+def test_should_skip_property_method() -> None:
+    source = (
+        "class Cache:\n"
+        "    @property\n"
+        "    def capacity(self) -> int:\n"
+        "        first_calculation = self._capacity\n"
+        "        adjusted = first_calculation - self._reserved\n"
+        "        return adjusted\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"@property methods exempt, got: {issues!r}"
+
+
+def test_should_skip_short_function() -> None:
+    source = "def double(value: int) -> int:\n    return value * 2\n"
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Functions <=3 lines exempt, got: {issues!r}"
+
+
+def test_should_skip_abstract_method() -> None:
+    source = (
+        "from abc import abstractmethod\n"
+        "\n"
+        "class Repository:\n"
+        "    @abstractmethod\n"
+        "    def fetch(self, key: str) -> int:\n"
+        "        ...\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"@abstractmethod exempt, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_format(_function_with_param_no_docstring(), TEST_FILE_PATH)
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_format(
+        _function_with_param_no_docstring(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_format("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_should_skip_short_function_with_docstring() -> None:
+    source = (
+        "def double(value: int) -> int:\n"
+        '    """Multiply the value by two.\n'
+        "\n"
+        "    The calculation uses left-shift internally.\n"
+        '    """\n'
+        "    return value * 2\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Short function with docstring must be exempt, got: {issues!r}"
+    )
+
+
+def test_should_not_count_self_or_cls_as_documentable_params() -> None:
+    source = (
+        "class Cache:\n"
+        "    def reset(self) -> None:\n"
+        '        """Drop all cached entries."""\n'
+        "        self._storage.clear()\n"
+        "        self._hits = 0\n"
+        "        self._misses = 0\n"
+    )
+    issues = check_docstring_format(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"self-only methods must not require Args:, got: {issues!r}"

package/hooks/blocking/test_code_rules_enforcer_inline_tuple_string_magic.py

@@ -0,0 +1,130 @@
+"""Unit tests for the inline-tuple snake_case-string-magic check in code_rules_enforcer.
+
+These tests cover the gap surfaced during PR #419: a tuple literal whose first
+element is a snake_case string (e.g. ``("kept", "Unknown status")``) inside a
+function body slipped past the Write/Edit hook even though the commit-time
+gate caught it.
+"""
+
+import importlib.util
+import pathlib
+import sys
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "code_rules_enforcer",
+    _HOOK_DIR / "code_rules_enforcer.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+check_inline_tuple_string_magic = hook_module.check_inline_tuple_string_magic
+validate_content = hook_module.validate_content
+
+PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
+TEST_FILE_PATH = "packages/app/services/test_loader.py"
+CONFIG_FILE_PATH = "packages/app/config/labels.py"
+
+
+def test_should_flag_inline_snake_case_tuple_pair_inside_function() -> None:
+    content = "def describe(glyph):\n    return {'a': ('kept', 'Unknown status')}\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert any("'kept'" in each_issue for each_issue in issues), (
+        f"Expected 'kept' tuple-pair flagged, got: {issues}"
+    )
+
+
+def test_should_flag_inline_snake_case_tuple_inside_dict_value() -> None:
+    content = "def lookup():\n    return {'STATUS_KEPT': ('kept', 'Patch unchanged')}\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert any("'kept'" in each_issue for each_issue in issues), (
+        f"Expected nested tuple flagged, got: {issues}"
+    )
+
+
+def test_should_flag_first_element_snake_case_with_underscore() -> None:
+    content = "def label():\n    return ('unknown_status', 'placeholder')\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert any("'unknown_status'" in each_issue for each_issue in issues), (
+        f"Expected snake_case-with-underscore flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_tuple_outside_function_body() -> None:
+    content = "ALL_STATUS = ('kept', 'Unknown status')\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Module-level constants are not in function bodies; must not flag, got: {issues}"
+    )
+
+
+def test_should_skip_test_files() -> None:
+    content = "def test_thing():\n    return ('kept', 'Unknown status')\n"
+    issues = check_inline_tuple_string_magic(content, TEST_FILE_PATH)
+    assert issues == [], f"Test files are exempt, got: {issues}"
+
+
+def test_should_skip_config_files() -> None:
+    content = "def build():\n    return ('kept', 'Unknown status')\n"
+    issues = check_inline_tuple_string_magic(content, CONFIG_FILE_PATH)
+    assert issues == [], f"Config files are exempt, got: {issues}"
+
+
+def test_should_not_flag_tuple_with_non_snake_case_first_element() -> None:
+    content = "def render():\n    return ('Title Case', 'Body')\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Non-snake-case strings are not column/key-like; must not flag, got: {issues}"
+    )
+
+
+def test_should_not_flag_short_string_first_element() -> None:
+    content = "def render():\n    return ('ok', 'fine')\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Strings shorter than minimum length are exempt, got: {issues}"
+    )
+
+
+def test_should_not_flag_keyword_strings() -> None:
+    content = "def render():\n    return ('true', 'false')\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"Keyword literals (true/false/none/null) are exempt, got: {issues}"
+    )
+
+
+def test_should_not_flag_tuple_longer_than_pair() -> None:
+    content = "def render():\n    return ('kept', 'Unknown status', 'extra')\n"
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Only two-element tuples are inspected, got: {issues}"
+
+
+def test_should_dedupe_nested_function_tuples() -> None:
+    """Tuples inside nested FunctionDefs must produce one finding, not many.
+
+    Without deduplication the outer ast.walk enumerates every FunctionDef
+    including nested ones, then the inner walk visits each tuple via every
+    enclosing function. Must surface exactly one finding per tuple site.
+    """
+    content = (
+        "def outer():\n"
+        "    def inner():\n"
+        '        x = ("some_column_name", 42)\n'
+        "        return x\n"
+        "    return inner\n"
+    )
+    issues = check_inline_tuple_string_magic(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1, f"expected 1 finding, got {len(issues)}: {issues!r}"
+
+
+def test_validate_content_wires_check_for_python_files() -> None:
+    content = "def describe(glyph):\n    return {'a': ('kept', 'Unknown status')}\n"
+    issues = validate_content(content, PRODUCTION_FILE_PATH)
+    assert any("'kept'" in each_issue for each_issue in issues), (
+        f"validate_content must run the new check, got: {issues}"
+    )

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)}"