claude-dev-env 1.82.0 → 1.84.0

package/hooks/blocking/test_code_rules_enforcer_module_docstring_roster.py

@@ -93,6 +93,46 @@ def test_should_not_flag_module_docstring_naming_every_public_check() -> None:
     assert issues == [], f"Docstring naming every check must not flag, got: {issues!r}"
 
 
+def _registry_module_omitting_check_via_shared_tokens_only() -> str:
+    return (
+        '"""Bare string-literal magic, inline literal-collection, inline tuple '
+        'string-magic, and whitespace-indentation magic checks."""\n'
+        "\n"
+        "def check_string_literal_magic(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_join_separator_string_magic(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_inline_literal_collections(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_inline_tuple_string_magic(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+        "\n"
+        "def check_whitespace_indentation_magic(content: str, file_path: str) -> list[str]:\n"
+        "    return []\n"
+    )
+
+
+def test_should_flag_check_named_only_by_tokens_shared_with_siblings() -> None:
+    issues = check_module_docstring_names_public_checks(
+        _registry_module_omitting_check_via_shared_tokens_only(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert any("check_join_separator_string_magic" in each for each in issues), (
+        "A check whose only summary-present tokens ('string', 'magic') are shared with "
+        f"sibling checks must flag as omitted, got: {issues!r}"
+    )
+    assert not any("check_string_literal_magic" in each for each in issues), (
+        f"A check the summary names ('string-literal magic') must not flag, got: {issues!r}"
+    )
+    assert not any("check_inline_literal_collections" in each for each in issues), (
+        "A check named by a stemmed token ('collection' for 'collections') must not "
+        f"flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
 def test_should_not_flag_module_with_a_single_public_check() -> None:
     source = (
         '"""Skip-decorator test-quality check."""\n'

package/hooks/blocking/test_code_rules_enforcer_naive_datetime.py

@@ -0,0 +1,213 @@
+"""Tests for the naive-datetime-construction check in code_rules_imports_logging.py.
+
+The check catches the DST-fold-ambiguity class Copilot flagged on
+python-automation PR #557: ``datetime.fromtimestamp(epoch)`` builds a datetime
+with no timezone, and a later ``.astimezone()`` on that naive value has to guess
+the local offset. The check flags the naive-producing constructors
+(``fromtimestamp``/``utcfromtimestamp`` without ``tz=``, and ``utcnow``) and
+leaves a ``tz=``-carrying call, and a plain ``now()``, alone.
+"""
+
+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()
+
+PRODUCTION_FILE_PATH = "/project/src/export_verification.py"
+TEST_FILE_PATH = "/project/src/test_export_verification.py"
+
+
+def check_naive_datetime_construction(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_naive_datetime_construction(content, file_path)
+
+
+def test_flags_fromtimestamp_without_timezone() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def describe(stamp: float) -> str:\n"
+        "    return datetime.fromtimestamp(stamp).astimezone().isoformat()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "fromtimestamp" in issues[0]
+    assert "tz=" in issues[0]
+
+
+def test_flags_utcfromtimestamp_and_utcnow() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def build(stamp: float) -> tuple[object, object]:\n"
+        "    return datetime.utcfromtimestamp(stamp), datetime.utcnow()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 2
+
+
+def test_flags_module_qualified_datetime_call() -> None:
+    content = (
+        "import datetime\n"
+        "def describe(stamp: float) -> object:\n"
+        "    return datetime.datetime.fromtimestamp(stamp)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_allows_fromtimestamp_with_timezone_keyword() -> None:
+    content = (
+        "from datetime import datetime, timezone\n"
+        "def describe(stamp: float) -> str:\n"
+        "    return datetime.fromtimestamp(stamp, tz=timezone.utc).isoformat()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_allows_fromtimestamp_with_positional_timezone() -> None:
+    content = (
+        "from datetime import datetime, timezone\n"
+        "def describe(stamp: float) -> str:\n"
+        "    return datetime.fromtimestamp(stamp, timezone.utc).isoformat()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_allows_module_qualified_fromtimestamp_with_positional_timezone() -> None:
+    content = (
+        "import datetime\n"
+        "def describe(stamp: float) -> object:\n"
+        "    return datetime.datetime.fromtimestamp(stamp, datetime.timezone.utc)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_flags_utcfromtimestamp_with_second_positional_argument() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def describe(stamp: float, other: float) -> object:\n"
+        "    return datetime.utcfromtimestamp(stamp, other)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_ignores_unrelated_datetime_attribute_chain() -> None:
+    content = (
+        "def describe(foo: object, stamp: float) -> object:\n"
+        "    return foo.datetime.fromtimestamp(stamp)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_flags_fromtimestamp_with_none_timezone_keyword() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def describe(stamp: float) -> object:\n"
+        "    return datetime.fromtimestamp(stamp, tz=None)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_flags_fromtimestamp_with_none_positional_timezone() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def describe(stamp: float) -> object:\n"
+        "    return datetime.fromtimestamp(stamp, None)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_flags_utcfromtimestamp_even_with_timezone_keyword() -> None:
+    content = (
+        "from datetime import datetime, timezone\n"
+        "def describe(stamp: float) -> object:\n"
+        "    return datetime.utcfromtimestamp(stamp, tz=timezone.utc)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_utcnow_remediation_points_at_now_not_utcnow_tz() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def stamp() -> object:\n"
+        "    return datetime.utcnow()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "now(tz=" in issues[0]
+
+
+def test_utcfromtimestamp_remediation_points_at_fromtimestamp() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def build(stamp: float) -> object:\n"
+        "    return datetime.utcfromtimestamp(stamp)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "fromtimestamp(" in issues[0]
+    assert "tz=" in issues[0]
+
+
+def test_utcfromtimestamp_remediation_uses_generic_placeholder() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def build(epoch_seconds: float) -> object:\n"
+        "    return datetime.utcfromtimestamp(epoch_seconds)\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "..., tz=" in issues[0]
+    assert "stamp, tz=" not in issues[0]
+
+
+def test_remediation_does_not_mandate_astimezone() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def stamp() -> object:\n"
+        "    return datetime.utcnow()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "then .astimezone()" not in issues[0]
+    assert "only when local display" in issues[0]
+
+
+def test_allows_plain_now() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def stamp() -> str:\n"
+        "    return datetime.now().isoformat()\n"
+    )
+    issues = check_naive_datetime_construction(content, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_exempts_test_files() -> None:
+    content = (
+        "from datetime import datetime\n"
+        "def describe(stamp: float) -> object:\n"
+        "    return datetime.fromtimestamp(stamp)\n"
+    )
+    issues = check_naive_datetime_construction(content, TEST_FILE_PATH)
+    assert issues == []

package/hooks/blocking/test_code_rules_enforcer_referenced_underscore_loop.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+
+from pathlib import Path
+import importlib.util
+
+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"
+CONFTEST_FILE_PATH = "packages/app/tests/conftest.py"
+
+
+def test_should_flag_referenced_underscore_loop_variable_in_conftest() -> None:
+    source = (
+        "import sys\n"
+        "\n"
+        "for _foreign_module_name in ['a', 'b']:\n"
+        "    del sys.modules[_foreign_module_name]\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, CONFTEST_FILE_PATH
+    )
+    assert any("_foreign_module_name" in each_issue for each_issue in issues), (
+        f"Expected referenced underscore loop variable flagged, got: {issues}"
+    )
+
+
+def test_should_flag_referenced_underscore_loop_variable_in_production() -> None:
+    source = (
+        "import sys\n"
+        "\n"
+        "def purge(all_names: list) -> None:\n"
+        "    for _name in all_names:\n"
+        "        del sys.modules[_name]\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("_name" in each_issue for each_issue in issues), (
+        f"Expected referenced underscore loop variable flagged, got: {issues}"
+    )
+
+
+def test_should_not_flag_unreferenced_underscore_throwaway() -> None:
+    source = "def spin(count: int) -> None:\n    for _unused in range(count):\n        pass\n"
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Genuinely unused underscore throwaway must pass, got: {issues}"
+
+
+def test_should_not_flag_bare_underscore_target() -> None:
+    source = "def spin(count: int) -> None:\n    for _ in range(count):\n        return None\n"
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"Bare '_' target must pass, got: {issues}"
+
+
+def test_should_not_flag_named_loop_variable_without_underscore() -> None:
+    source = (
+        "import sys\n\nfor each_module_name in ['a', 'b']:\n    del sys.modules[each_module_name]\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, CONFTEST_FILE_PATH
+    )
+    assert issues == [], f"each_-prefixed loop variable without underscore must pass, got: {issues}"
+
+
+def test_should_not_flag_underscore_loop_variable_shadowed_by_comprehension() -> None:
+    source = (
+        "def collect(all_names: list, other: list) -> list:\n"
+        "    all_other: list = []\n"
+        "    for _name in all_names:\n"
+        "        all_other = [_name for _name in other]\n"
+        "    return all_other\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"Comprehension rebinding the loop name shadows the outer read, must pass, got: {issues}"
+    )
+
+
+def test_should_flag_underscore_loop_variable_read_inside_non_rebinding_comprehension() -> None:
+    source = (
+        "def collect(all_names: list, other: list) -> list:\n"
+        "    matches: list = []\n"
+        "    for _name in all_names:\n"
+        "        matches = [each_row for each_row in other if each_row == _name]\n"
+        "    return matches\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("_name" in each_issue for each_issue in issues), (
+        f"A comprehension reading the outer loop name without rebinding it must flag, got: {issues}"
+    )
+
+
+def test_should_not_flag_underscore_loop_variable_shadowed_by_lambda_parameter() -> None:
+    source = (
+        "def build(all_names: list) -> list:\n"
+        "    all_callables: list = []\n"
+        "    for _name in all_names:\n"
+        "        all_callables.append(lambda _name: _name)\n"
+        "    return all_callables\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A lambda parameter shadowing the loop name owns its body, must pass, got: {issues}"
+    )
+
+
+def test_should_not_flag_underscore_loop_variable_shadowed_by_nested_def_parameter() -> None:
+    source = (
+        "def build(all_names: list) -> None:\n"
+        "    for _handler in all_names:\n"
+        "        def inner(_handler: object) -> object:\n"
+        "            return _handler\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A nested-def parameter shadowing the loop name owns its body, must pass, got: {issues}"
+    )
+
+
+def test_should_not_flag_outer_underscore_loop_variable_shadowed_by_nested_loop() -> None:
+    source = (
+        "import sys\n"
+        "\n"
+        "def purge(first: list, second: list) -> None:\n"
+        "    for _name in first:\n"
+        "        for _name in second:\n"
+        "            del sys.modules[_name]\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert not any("Line 4" in each_issue for each_issue in issues), (
+        f"Outer loop whose name a nested loop rebinds is never read in the outer scope, "
+        f"got: {issues}"
+    )
+
+
+def test_should_flag_underscore_loop_variable_read_before_nested_shadowing_loop() -> None:
+    source = (
+        "import sys\n"
+        "\n"
+        "def purge(first: list, second: list) -> None:\n"
+        "    for _name in first:\n"
+        "        del sys.modules[_name]\n"
+        "        for _name in second:\n"
+        "            pass\n"
+    )
+    issues = code_rules_enforcer.check_referenced_underscore_loop_variable(
+        source, PRODUCTION_FILE_PATH
+    )
+    assert any("Line 4" in each_issue for each_issue in issues), (
+        f"The outer loop body reads its own name before the nested loop rebinds it, "
+        f"must flag, got: {issues}"
+    )

package/hooks/blocking/test_code_rules_enforcer_split_constants_config.py

@@ -177,6 +177,39 @@ def test_advisory_should_flag_outer_constants_after_nested_def() -> None:
     )
 
 
+def test_scan_function_body_constants_skips_docstring_contrast_line() -> None:
+    source = (
+        "def demo(label):\n"
+        '    """Flag a boolean assignment whose target and callee clash.\n'
+        "\n"
+        "    ::\n"
+        "\n"
+        "        FLAG: ready = make_stale(...)\n"
+        '    """\n'
+        "    return label\n"
+    )
+    advisory_issues = code_rules_enforcer._scan_function_body_constants(source)
+    assert advisory_issues == [], (
+        f"Expected no function-local constant issue on an illustrative row, got: {advisory_issues}"
+    )
+
+
+def test_scan_function_body_constants_still_flags_real_function_body_constant() -> None:
+    source = (
+        "def demo(label):\n"
+        '    """Flag a boolean assignment whose target and callee clash.\n'
+        "\n"
+        "        FLAG: ready = make_stale(...)\n"
+        '    """\n'
+        "    SOME_CONST = 3\n"
+        "    return SOME_CONST\n"
+    )
+    advisory_issues = code_rules_enforcer._scan_function_body_constants(source)
+    assert any("SOME_CONST" in issue for issue in advisory_issues), (
+        f"Expected the real function-body constant SOME_CONST to stay flagged, got: {advisory_issues}"
+    )
+
+
 def test_check_constants_outside_config_flags_annotated_assignment() -> None:
     source = "TEXT_FILE_ENCODING: str = 'utf-8'\n"
     issues = code_rules_enforcer.check_constants_outside_config(

package/hooks/blocking/test_code_rules_enforcer_split_shared.py

@@ -18,14 +18,37 @@ from code_rules_enforcer import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     changed_line_numbers,
+    docstring_line_numbers,
 )
 
 code_rules_enforcer = SimpleNamespace(
     changed_line_numbers=changed_line_numbers,
+    docstring_line_numbers=docstring_line_numbers,
     prior_and_post_edit_content=prior_and_post_edit_content,
 )
 
 
+def test_docstring_line_numbers_spans_a_multi_line_function_docstring() -> None:
+    source = (
+        "def describe():\n"
+        '    """First row.\n'
+        "\n"
+        "    Third row.\n"
+        '    """\n'
+        "    return 1\n"
+    )
+    assert code_rules_enforcer.docstring_line_numbers(source) == {2, 3, 4, 5}
+
+
+def test_docstring_line_numbers_excludes_real_code_lines() -> None:
+    source = "def compute():\n    counter = 41\n    return counter\n"
+    assert code_rules_enforcer.docstring_line_numbers(source) == set()
+
+
+def test_docstring_line_numbers_returns_empty_set_on_syntax_error() -> None:
+    assert code_rules_enforcer.docstring_line_numbers("def broken(:\n") == set()
+
+
 def test_readable_prior_yields_consistent_prior_and_reconstruction(tmp_path) -> None:
     """When the prior reads cleanly, the helper returns the same prior content it
     reconstructed the post-edit view from, so the two never diverge across two