claude-dev-env 1.77.0 → 1.79.0

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -152,7 +152,7 @@ def test_does_not_flag_constant_imported_one_directory_up(neutral_root: Path) ->
     assert issues == [], f"No constant is dead when all are imported, got: {issues}"
 
 
-def test_does_not_flag_when_module_declares_dunder_all(neutral_root: Path) -> None:
+def test_does_not_flag_dunder_all_member_with_a_live_consumer(neutral_root: Path) -> None:
     constants_body = CONSTANTS_BODY + '__all__ = ["MEDIUM_TERMINAL"]\n'
     consumer_body = (
         "from report_constants.render_report_constants import MEDIUM_TERMINAL\n"
@@ -164,7 +164,35 @@ def test_does_not_flag_when_module_declares_dunder_all(neutral_root: Path) -> No
         neutral_root / "workflow", constants_body, consumer_body
     )
     issues = _check(constants_body, str(constants_path))
-    assert issues == [], f"__all__ surface suppresses the check, got: {issues}"
+    assert issues == [], f"An __all__ member a consumer imports stays live, got: {issues}"
+
+
+def test_dunder_all_narrows_check_to_exported_constants(neutral_root: Path) -> None:
+    constants_body = (
+        'JSONL_APPEND_OPEN_MODE = "a"\n'
+        'ZIPFILE_READ_OPEN_MODE = "r"\n'
+        "PRIVATE_BUFFER_BYTES = 1024\n"
+        '__all__ = ["JSONL_APPEND_OPEN_MODE", "ZIPFILE_READ_OPEN_MODE"]\n'
+    )
+    consumer_body = (
+        "from report_constants.render_report_constants import JSONL_APPEND_OPEN_MODE\n"
+        "\n"
+        "def open_mode() -> str:\n"
+        "    return JSONL_APPEND_OPEN_MODE\n"
+    )
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", constants_body, consumer_body
+    )
+    issues = _check(constants_body, str(constants_path))
+    assert any("ZIPFILE_READ_OPEN_MODE" in each_issue for each_issue in issues), (
+        f"An exported constant no module imports is dead, got: {issues}"
+    )
+    assert not any("JSONL_APPEND_OPEN_MODE" in each_issue for each_issue in issues), (
+        f"An exported constant a consumer imports must not be flagged, got: {issues}"
+    )
+    assert not any("PRIVATE_BUFFER_BYTES" in each_issue for each_issue in issues), (
+        f"A constant __all__ omits is the author's private value and is exempt, got: {issues}"
+    )
 
 
 def test_does_not_run_on_ordinary_production_module(neutral_root: Path) -> None:
@@ -264,6 +292,65 @@ def test_does_not_flag_constant_used_only_in_a_sibling_tree(neutral_root: Path)
     )
 
 
+def _build_name_collision_repository(
+    repository_root: Path,
+    promoter_timing_body: str,
+    promoter_consumer_body: str,
+    harness_constants_body: str,
+    harness_consumer_body: str,
+) -> Path:
+    promoter_config = repository_root / "promoter" / "config"
+    promoter_config.mkdir(parents=True)
+    timing_path = promoter_config / "timing.py"
+    timing_path.write_text(promoter_timing_body, encoding="utf-8")
+    (repository_root / "promoter" / "runtime.py").write_text(
+        promoter_consumer_body, encoding="utf-8"
+    )
+    harness_config = repository_root / "harness" / "config"
+    harness_config.mkdir(parents=True)
+    (harness_config / "lockfile_constants.py").write_text(
+        harness_constants_body, encoding="utf-8"
+    )
+    (repository_root / "harness" / "lockfile.py").write_text(
+        harness_consumer_body, encoding="utf-8"
+    )
+    return timing_path
+
+
+def test_same_named_constant_in_an_unrelated_module_does_not_mask_a_dead_one(
+    neutral_root: Path,
+) -> None:
+    promoter_timing_body = "LOCKFILE_ACQUIRE_BYTE_LENGTH = 1\nSWEEP_INTERVAL_SECONDS = 30\n"
+    promoter_consumer_body = (
+        "from config.timing import SWEEP_INTERVAL_SECONDS\n"
+        "\n"
+        "def deadline() -> int:\n"
+        "    return SWEEP_INTERVAL_SECONDS\n"
+    )
+    harness_constants_body = "LOCKFILE_ACQUIRE_BYTE_LENGTH = 1\n"
+    harness_consumer_body = (
+        "from harness.config.lockfile_constants import LOCKFILE_ACQUIRE_BYTE_LENGTH\n"
+        "\n"
+        "def acquire() -> int:\n"
+        "    return LOCKFILE_ACQUIRE_BYTE_LENGTH\n"
+    )
+    timing_path = _build_name_collision_repository(
+        neutral_root,
+        promoter_timing_body,
+        promoter_consumer_body,
+        harness_constants_body,
+        harness_consumer_body,
+    )
+    issues = _check(promoter_timing_body, str(timing_path))
+    assert any("LOCKFILE_ACQUIRE_BYTE_LENGTH" in each_issue for each_issue in issues), (
+        "A constant whose only same-named twin lives in an unrelated module's "
+        f"import must still be flagged dead, got: {issues}"
+    )
+    assert not any("SWEEP_INTERVAL_SECONDS" in each_issue for each_issue in issues), (
+        f"A constant consumed within its own package must not be flagged, got: {issues}"
+    )
+
+
 def test_returns_empty_list_at_file_cap(
     neutral_root: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:

package/hooks/blocking/test_code_rules_enforcer_dead_split_branch.py

@@ -0,0 +1,105 @@
+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)
+assert specification is not None and specification.loader is not None
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_PATH = "C:/project/pkg/menu_info_colors.py"
+
+
+def _check(source: str) -> list[str]:
+    return code_rules_enforcer.check_dead_split_truthiness_branch(source, PRODUCTION_PATH)
+
+
+def test_flags_split_truthiness_else_arm() -> None:
+    source = (
+        "def _extract_uid_prefix(uid: str) -> str:\n"
+        '    all_parts = uid.split("_")\n'
+        "    if len(all_parts) > 2:\n"
+        '        return "_".join(all_parts[:3])\n'
+        "    return all_parts[0] if all_parts else uid\n"
+    )
+    issues = _check(source)
+    assert len(issues) == 1
+    assert "all_parts" in issues[0]
+    assert "Line 5" in issues[0]
+
+
+def test_flags_negated_guard_dead_body() -> None:
+    source = (
+        "def first_segment(path: str) -> str:\n"
+        '    all_segments = path.split("/")\n'
+        "    if not all_segments:\n"
+        "        return path\n"
+        "    return all_segments[0]\n"
+    )
+    issues = _check(source)
+    assert len(issues) == 1
+    assert "all_segments" in issues[0]
+
+
+def test_does_not_flag_split_without_separator() -> None:
+    source = (
+        "def first_token(text: str) -> str:\n"
+        "    all_parts = text.split()\n"
+        "    return all_parts[0] if all_parts else text\n"
+    )
+    assert _check(source) == []
+
+
+def test_does_not_flag_length_comparison_guard() -> None:
+    source = (
+        "def prefix(uid: str) -> str:\n"
+        '    all_parts = uid.split("_")\n'
+        "    if len(all_parts) > 1:\n"
+        "        return all_parts[0]\n"
+        "    return uid\n"
+    )
+    assert _check(source) == []
+
+
+def test_does_not_flag_when_name_reassigned() -> None:
+    source = (
+        "def normalize(uid: str) -> str:\n"
+        '    all_parts = uid.split("_")\n'
+        "    all_parts = [each_part.strip() for each_part in all_parts]\n"
+        "    return all_parts[0] if all_parts else uid\n"
+    )
+    assert _check(source) == []
+
+
+def test_does_not_flag_when_name_is_parameter() -> None:
+    source = (
+        "def shape(all_parts: list[str]) -> str:\n"
+        '    all_parts = "x".split("_")\n'
+        '    return all_parts[0] if all_parts else ""\n'
+    )
+    assert _check(source) == []
+
+
+def test_does_not_flag_attribute_receiver_split() -> None:
+    source = (
+        "def first(s: object) -> object:\n"
+        '    parts = s.str.split(",")\n'
+        "    return parts[0] if parts else 0\n"
+    )
+    assert _check(source) == []
+
+
+def test_does_not_flag_in_test_file() -> None:
+    source = (
+        "def helper(uid: str) -> str:\n"
+        '    all_parts = uid.split("_")\n'
+        "    return all_parts[0] if all_parts else uid\n"
+    )
+    assert (
+        code_rules_enforcer.check_dead_split_truthiness_branch(
+            source, "C:/project/pkg/test_thing.py"
+        )
+        == []
+    )

package/hooks/blocking/test_code_rules_enforcer_docstring_field_runmode_outcome.py

@@ -0,0 +1,129 @@
+"""Tests for check_docstring_field_runmode_outcome — O6 run-mode-vs-per-record drift.
+
+A dataclass field whose name marks a run-mode flag (``is_dry_run``) is documented
+in the class Attributes block with per-record write-outcome prose ("True when no
+STP was written"), while the value is set the same way for every record from the
+run mode (``is_dry_run=not is_execute``). An already-OK record in an execute run
+writes no file yet still stores ``False``, so the per-record prose misleads every
+reader. This is the deterministic single-file slice of Category O6 drift.
+"""
+
+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_field_runmode_outcome(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_field_runmode_outcome(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/src/jsonl_writer.py"
+TEST_FILE_PATH = "/project/src/test_jsonl_writer.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _drifted_record() -> str:
+    return (
+        "@dataclass(frozen=True)\n"
+        "class PerThemeJsonlRecord:\n"
+        '    """Exact schema for the per-theme JSONL line.\n'
+        "\n"
+        "    Attributes:\n"
+        "        theme_name: Theme directory basename.\n"
+        "        is_dry_run: True when no STP was written.\n"
+        '    """\n'
+        "\n"
+        "    theme_name: str\n"
+        "    is_dry_run: bool\n"
+    )
+
+
+def _run_mode_record() -> str:
+    return (
+        "@dataclass(frozen=True)\n"
+        "class PerThemeJsonlRecord:\n"
+        '    """Exact schema for the per-theme JSONL line.\n'
+        "\n"
+        "    Attributes:\n"
+        "        theme_name: Theme directory basename.\n"
+        "        is_dry_run: True for a dry run; False for an execute run.\n"
+        '    """\n'
+        "\n"
+        "    theme_name: str\n"
+        "    is_dry_run: bool\n"
+    )
+
+
+def test_flags_run_mode_field_documented_as_per_record_write_outcome() -> None:
+    issues = check_docstring_field_runmode_outcome(_drifted_record(), PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "is_dry_run" in issues[0]
+    assert "run-mode" in issues[0]
+
+
+def test_run_mode_phrasing_is_left_alone() -> None:
+    issues = check_docstring_field_runmode_outcome(_run_mode_record(), PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_multiline_description_continuation_still_flags() -> None:
+    source = (
+        "@dataclass\n"
+        "class Record:\n"
+        '    """Schema.\n'
+        "\n"
+        "    Attributes:\n"
+        "        is_dry_run: True for the record when\n"
+        "            no STP was written.\n"
+        '    """\n'
+        "\n"
+        "    is_dry_run: bool\n"
+    )
+    issues = check_docstring_field_runmode_outcome(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_non_run_mode_field_with_write_outcome_is_left_alone() -> None:
+    source = (
+        "@dataclass\n"
+        "class Record:\n"
+        '    """Schema.\n'
+        "\n"
+        "    Attributes:\n"
+        "        stp_path: Path the STP was written to disk.\n"
+        '    """\n'
+        "\n"
+        "    stp_path: str\n"
+    )
+    issues = check_docstring_field_runmode_outcome(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_test_file_is_exempt() -> None:
+    issues = check_docstring_field_runmode_outcome(_drifted_record(), TEST_FILE_PATH)
+    assert issues == []
+
+
+def test_hook_infrastructure_is_exempt() -> None:
+    issues = check_docstring_field_runmode_outcome(_drifted_record(), HOOK_INFRASTRUCTURE_PATH)
+    assert issues == []
+
+
+def test_syntax_error_returns_no_issues() -> None:
+    issues = check_docstring_field_runmode_outcome("class Record(\n", PRODUCTION_FILE_PATH)
+    assert issues == []

package/hooks/blocking/test_code_rules_enforcer_docstring_length_constant_superlative.py

@@ -0,0 +1,198 @@
+"""Tests for check_docstring_length_constant_superlative_vs_exact_gate.
+
+A config module defines an integer ``*_LENGTH`` constant and its docstring
+describes it with a superlative word ("the longest color string the swatch
+accepts"), while the only consumer treats the constant as an exact-length
+equality gate ("len(hex_color) != COLOR_AARRGGBB_LENGTH") in a sibling module.
+A shorter valid string is rejected, not accepted at a shorter length, so the
+"longest" prose claims a range of accepted lengths the code never allows. This
+is the deterministic exact-gate slice of Category O6/O8
+docstring-vs-implementation drift.
+
+The package trees these tests build live under a neutral OS temp directory
+rather than the pytest ``tmp_path`` fixture: the production check exempts any
+path containing "test", and the pytest fixture root carries that substring, so a
+fixture-rooted package would be skipped as test code and prove nothing.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import tempfile
+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_length_gate(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_length_constant_superlative_vs_exact_gate(
+        content, file_path
+    )
+
+
+SUPERLATIVE_SWATCH_MODULE = '''"""Color-swatch rendering constants for the HTML run report.
+
+These constants name the longest color string the swatch accepts and the
+channel maximum the alpha byte is divided by.
+"""
+
+from typing import Final
+
+COLOR_AARRGGBB_LENGTH: Final[int] = 9
+'''
+
+
+def _run_gate_over_package(
+    swatch_content: str, consumer_body: str, swatch_basename: str = "color_swatch.py"
+) -> list[str]:
+    with tempfile.TemporaryDirectory() as temp_root:
+        config_directory = Path(temp_root) / "stp_contrast_fix" / "config"
+        config_directory.mkdir(parents=True)
+        swatch_path = config_directory / swatch_basename
+        swatch_path.write_text(swatch_content, encoding="utf-8")
+        consumer_path = config_directory.parent / "html_report_fragments.py"
+        consumer_path.write_text(consumer_body, encoding="utf-8")
+        return check_length_gate(swatch_content, str(swatch_path))
+
+
+def test_superlative_describing_exact_length_gate_is_flagged() -> None:
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> str | None:\n"
+        '    if not hex_color.startswith("#") or len(hex_color) != '
+        "COLOR_AARRGGBB_LENGTH:\n"
+        "        return None\n"
+        "    return hex_color\n"
+    )
+    issues = _run_gate_over_package(SUPERLATIVE_SWATCH_MODULE, consumer_body)
+    assert len(issues) == 1
+    assert "COLOR_AARRGGBB_LENGTH" in issues[0]
+
+
+def test_ordered_comparison_treated_as_maximum_is_not_flagged() -> None:
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def truncated(hex_color: str) -> bool:\n"
+        "    return len(hex_color) <= COLOR_AARRGGBB_LENGTH\n"
+    )
+    assert _run_gate_over_package(SUPERLATIVE_SWATCH_MODULE, consumer_body) == []
+
+
+def test_no_superlative_phrase_is_not_flagged() -> None:
+    plain_module = (
+        '"""The exact required #AARRGGBB length the swatch renders."""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> bool:\n"
+        "    return len(hex_color) == COLOR_AARRGGBB_LENGTH\n"
+    )
+    assert _run_gate_over_package(plain_module, consumer_body) == []
+
+
+def test_constant_without_length_suffix_is_not_flagged() -> None:
+    non_length_module = (
+        '"""The longest swatch threshold value used by the renderer."""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_CHANNEL_MAXIMUM: Final[int] = 255\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_CHANNEL_MAXIMUM\n\n\n"
+        "def saturated(channel: str) -> bool:\n"
+        "    return len(channel) == COLOR_CHANNEL_MAXIMUM\n"
+    )
+    assert _run_gate_over_package(non_length_module, consumer_body) == []
+
+
+def test_constant_with_no_length_comparison_is_not_flagged() -> None:
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def pad(hex_color: str) -> str:\n"
+        "    return hex_color.ljust(COLOR_AARRGGBB_LENGTH)\n"
+    )
+    assert _run_gate_over_package(SUPERLATIVE_SWATCH_MODULE, consumer_body) == []
+
+
+def test_superlative_in_function_docstring_is_not_flagged() -> None:
+    function_docstring_module = (
+        '"""The exact #AARRGGBB length the swatch renders."""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n\n\n"
+        "def describe() -> str:\n"
+        '    """Return the longest color string the swatch accepts."""\n'
+        '    return "swatch"\n'
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> bool:\n"
+        "    return len(hex_color) == COLOR_AARRGGBB_LENGTH\n"
+    )
+    assert _run_gate_over_package(function_docstring_module, consumer_body) == []
+
+
+def test_superlative_bound_to_other_constant_is_not_flagged() -> None:
+    two_constant_module = (
+        '"""Color-swatch rendering constants for the HTML run report.\n\n'
+        "COLOR_AARRGGBB_LENGTH is the exact #AARRGGBB length the swatch renders.\n"
+        "MAX_NAME_LENGTH is the longest swatch label the legend lays out.\n"
+        '"""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n"
+        "MAX_NAME_LENGTH: Final[int] = 32\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH, MAX_NAME_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> str | None:\n"
+        "    if len(hex_color) != COLOR_AARRGGBB_LENGTH:\n"
+        "        return None\n"
+        "    return hex_color\n\n\n"
+        "def fits(label: str) -> bool:\n"
+        "    return len(label) <= MAX_NAME_LENGTH\n"
+    )
+    assert _run_gate_over_package(two_constant_module, consumer_body) == []
+
+
+def test_superlative_bound_to_exact_gated_constant_is_flagged() -> None:
+    two_constant_module = (
+        '"""Color-swatch rendering constants for the HTML run report.\n\n'
+        "COLOR_AARRGGBB_LENGTH is the longest #AARRGGBB string the swatch accepts.\n"
+        "MAX_NAME_LENGTH is the exact swatch label width the legend lays out.\n"
+        '"""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n"
+        "MAX_NAME_LENGTH: Final[int] = 32\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH, MAX_NAME_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> str | None:\n"
+        "    if len(hex_color) != COLOR_AARRGGBB_LENGTH:\n"
+        "        return None\n"
+        "    return hex_color\n\n\n"
+        "def fits(label: str) -> bool:\n"
+        "    return len(label) <= MAX_NAME_LENGTH\n"
+    )
+    issues = _run_gate_over_package(two_constant_module, consumer_body)
+    assert len(issues) == 1
+    assert "COLOR_AARRGGBB_LENGTH" in issues[0]
+    assert "MAX_NAME_LENGTH" not in issues[0]
+
+
+def test_syntax_error_returns_empty() -> None:
+    issues = check_length_gate(
+        "def broken(\n", "/stp_contrast_fix/config/color_swatch.py"
+    )
+    assert issues == []