claude-dev-env 2.9.0 → 2.11.0

package/hooks/blocking/test_code_rules_enforcer_docstring_args_span_scope.py

@@ -1,13 +1,15 @@
-"""Tests for check_docstring_args_single_line_scope_vs_span — Category O6 drift.
-
-A docstring Args: entry that scopes a finding to one named line ("only when its
-block-anchor line is among the changed lines") while the body builds a range()
-span and routes it through a span-intersection scoper claims a narrower scope
-than the code applies. The body blocks when ANY line of the span is among the
-changed lines, so an edit touching a non-anchor line of the span still blocks —
-contradicting the single-line Args sentence. This is the deterministic slice of
-Category O6 (free-form docstring-vs-implementation drift) for an Args entry whose
-single-line scope claim disagrees with a span-intersection body.
+"""Span-scope tests for docstring checks.
+
+Covers two surfaces:
+
+1. ``check_docstring_args_single_line_scope_vs_span`` (Category O6) — an Args
+   entry that claims single-line (block-anchor) scope while the body builds a
+   multi-line span and routes it through span intersection.
+
+2. Changed-span grading for ``check_docstring_runon_sentence`` and
+   ``check_docstring_prose_wall_without_illustration`` (issue #237) — far-away
+   no-op grandfathering, introduced-violation blocking, and
+   ``defer_scope_to_caller`` pass-through.
 """
 
 from __future__ import annotations
@@ -201,3 +203,223 @@ def test_hook_infrastructure_is_not_exempt() -> None:
     assert (
         len(check_docstring_args_single_line_scope_vs_span(content, HOOK_INFRASTRUCTURE_PATH)) == 1
     )
+
+# ---------------------------------------------------------------------------
+# Changed-span grading for the two whole-file docstring checks (issue #237 / P-41)
+# check_docstring_runon_sentence and check_docstring_prose_wall_without_illustration
+# ---------------------------------------------------------------------------
+
+
+def check_docstring_runon_sentence(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_runon_sentence(
+        content, file_path, all_changed_lines, defer_scope_to_caller
+    )
+
+
+def check_docstring_prose_wall_without_illustration(
+    content: str,
+    file_path: str,
+    all_changed_lines: set[int] | None = None,
+    defer_scope_to_caller: bool = False,
+) -> list[str]:
+    return code_rules_enforcer.check_docstring_prose_wall_without_illustration(
+        content, file_path, all_changed_lines, defer_scope_to_caller
+    )
+
+
+_CLEAN_HELPER_TAIL = (
+    "\n"
+    "def clean_helper() -> str:\n"
+    '    """Return a short status token for the board.\n'
+    "\n"
+    "    Each call names one vessel and its final port.\n"
+    '    """\n'
+    '    return "ok"\n'
+)
+
+
+def _module_with_far_away_runon_and_clean_helper() -> str:
+    return (
+        '"""Owns the SIGINT install/restore/installability check, the atexit terminal-record\n'
+        "registration, and the interrupted-run finalizer — the non-promoter-specific\n"
+        "machinery that brackets a run so the JSONL artifact always carries a terminal\n"
+        "record and an in-flight theme record on interrupt.\n"
+        '"""\n'
+        + _CLEAN_HELPER_TAIL
+    )
+
+
+def _module_with_far_away_prose_wall_and_clean_helper() -> str:
+    return (
+        '"""Assemble the nightly voyage tally from the harbor scans.\n'
+        "\n"
+        "A scan names one vessel and where it dropped anchor.\n"
+        "The tally walks the scans in arrival order and keeps that order.\n"
+        "A calm voyage ends well for every vessel it carried.\n"
+        "A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "The tally groups the vessels by their final port for the harbor.\n"
+        "The harbor reads the tally and sees every arrival at a glance.\n"
+        '"""\n'
+        + _CLEAN_HELPER_TAIL
+    )
+
+
+def test_runon_far_away_no_op_is_grandfathered() -> None:
+    content = _module_with_far_away_runon_and_clean_helper()
+    clean_helper_line = content.splitlines().index("def clean_helper() -> str:") + 1
+    all_changed_lines = set(range(clean_helper_line, clean_helper_line + 6))
+    unscoped = check_docstring_runon_sentence(content, PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in unscoped), (
+        f"control: unscoped must still see the far-away run-on, got {unscoped!r}"
+    )
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=all_changed_lines
+    )
+    assert scoped == [], (
+        f"far-away run-on must be grandfathered on a clean-helper edit, got {scoped!r}"
+    )
+
+
+def test_runon_introduced_violation_blocks() -> None:
+    content = _module_with_far_away_runon_and_clean_helper()
+    unscoped = check_docstring_runon_sentence(content, PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in unscoped)
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines={1}
+    )
+    assert any("run-on" in each for each in scoped), (
+        f"introduced/touched run-on must block, got {scoped!r}"
+    )
+
+
+def test_prose_wall_far_away_no_op_is_grandfathered() -> None:
+    content = _module_with_far_away_prose_wall_and_clean_helper()
+    clean_helper_line = content.splitlines().index("def clean_helper() -> str:") + 1
+    all_changed_lines = set(range(clean_helper_line, clean_helper_line + 6))
+    unscoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in unscoped), (
+        f"control: unscoped must still see the far-away wall, got {unscoped!r}"
+    )
+    scoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=all_changed_lines
+    )
+    assert scoped == [], (
+        f"far-away wall must be grandfathered on a clean-helper edit, got {scoped!r}"
+    )
+
+
+def test_prose_wall_introduced_violation_blocks() -> None:
+    content = _module_with_far_away_prose_wall_and_clean_helper()
+    unscoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in unscoped)
+    scoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH, all_changed_lines={1}
+    )
+    assert any("worked example" in each for each in scoped), (
+        f"introduced/touched wall must block, got {scoped!r}"
+    )
+
+
+def test_runon_defer_scope_returns_all_violations() -> None:
+    content = _module_with_far_away_runon_and_clean_helper()
+    deferred = check_docstring_runon_sentence(
+        content,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines={999},
+        defer_scope_to_caller=True,
+    )
+    assert any("run-on" in each for each in deferred)
+
+
+def _function_with_runon_docstring() -> str:
+    return (
+        "def clean_helper() -> str:\n"
+        '    """Owns the SIGINT install/restore/installability check, the atexit terminal-record\n'
+        "    registration, and the interrupted-run finalizer — the non-promoter-specific\n"
+        "    machinery that brackets a run so the JSONL artifact always carries a terminal\n"
+        "    record and an in-flight theme record on interrupt.\n"
+        '    """\n'
+        '    return "ok"\n'
+    )
+
+
+def test_runon_docstring_body_edit_blocks_without_def_line() -> None:
+    content = _function_with_runon_docstring()
+    unscoped = check_docstring_runon_sentence(content, PRODUCTION_FILE_PATH)
+    assert any("run-on" in each for each in unscoped), (
+        f"control: unscoped must see the function run-on, got {unscoped!r}"
+    )
+    docstring_body_lines = {2, 3, 4, 5}
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=docstring_body_lines
+    )
+    assert any("run-on" in each for each in scoped), (
+        f"docstring-body edit must block even when the def line is untouched, got {scoped!r}"
+    )
+
+
+def test_runon_post_docstring_body_edit_is_grandfathered() -> None:
+    content = _function_with_runon_docstring()
+    return_line = content.splitlines().index('    return "ok"') + 1
+    scoped = check_docstring_runon_sentence(
+        content, PRODUCTION_FILE_PATH, all_changed_lines={return_line}
+    )
+    assert scoped == [], (
+        f"post-docstring body edit must grandfather the pre-existing run-on, got {scoped!r}"
+    )
+
+
+def _function_with_prose_wall_docstring() -> str:
+    return (
+        "def clean_helper() -> str:\n"
+        '    """Assemble the nightly voyage tally from the harbor scans.\n'
+        "\n"
+        "    A scan names one vessel and where it dropped anchor.\n"
+        "    The tally walks the scans in arrival order and keeps that order.\n"
+        "    A calm voyage ends well for every vessel it carried.\n"
+        "    A halted voyage marks the vessel it was near when the storm arrived.\n"
+        "    A wrecked voyage marks the vessel that sank and stops the walk there.\n"
+        "    The tally groups the vessels by their final port for the harbor.\n"
+        "    The harbor reads the tally and sees every arrival at a glance.\n"
+        '    """\n'
+        '    return "ok"\n'
+    )
+
+
+def test_prose_wall_docstring_body_edit_blocks_without_def_line() -> None:
+    content = _function_with_prose_wall_docstring()
+    unscoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH
+    )
+    assert any("worked example" in each for each in unscoped), (
+        f"control: unscoped must see the function wall, got {unscoped!r}"
+    )
+    docstring_body_lines = set(range(2, 12))
+    scoped = check_docstring_prose_wall_without_illustration(
+        content, PRODUCTION_FILE_PATH, all_changed_lines=docstring_body_lines
+    )
+    assert any("worked example" in each for each in scoped), (
+        f"docstring-body edit must block even when the def line is untouched, got {scoped!r}"
+    )
+
+
+def test_prose_wall_defer_scope_returns_all_violations() -> None:
+    content = _module_with_far_away_prose_wall_and_clean_helper()
+    deferred = check_docstring_prose_wall_without_illustration(
+        content,
+        PRODUCTION_FILE_PATH,
+        all_changed_lines={999},
+        defer_scope_to_caller=True,
+    )
+    assert any("worked example" in each for each in deferred)
+

package/hooks/blocking/test_code_rules_enforcer_ephemeral.py

@@ -186,7 +186,7 @@ def test_should_return_false_for_pytest_tmp_path_when_job_dir_elsewhere(
     temp directory was an ephemeral source: pytest tmp_path fixtures live
     under tempfile.gettempdir(), so the enforcer's own test targets must not
     classify as ephemeral. CLAUDE_JOB_DIR points elsewhere (its scratch dir
-    lives under .claude-ev/jobs, not %TEMP%).
+    lives under .claude-profile-c/jobs, not %TEMP%).
     """
     monkeypatch.delenv("CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT", raising=False)
     monkeypatch.setenv("CLAUDE_JOB_DIR", str(tmp_path / "elsewhere"))

package/hooks/blocking/test_code_rules_enforcer_join_separator_magic.py

@@ -65,3 +65,44 @@ def test_should_report_join_separator_line_number() -> None:
     assert any("Line 2" in each_issue for each_issue in issues), (
         f"Expected line 2 reported, got: {issues}"
     )
+
+
+def test_should_grandfather_unchanged_join_separator_in_wide_edit() -> None:
+    prior_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    return ', '.join(str(each_path) for each_path in all_paths)\n"
+    )
+    proposed_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    # keep the join separator the same\n"
+        "    return ', '.join(str(each_path) for each_path in all_paths)\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    join_issues = [each for each in issues if "join" in each]
+    assert join_issues == [], (
+        f"unchanged enclosed join separator must be grandfathered, got: {join_issues}"
+    )
+
+
+def test_should_block_new_join_separator_in_wide_edit() -> None:
+    prior_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    return JOIN_DELIMITER.join(all_paths)\n"
+    )
+    proposed_fragment = (
+        "def render(all_paths: list) -> str:\n"
+        "    return ', '.join(all_paths)\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    join_issues = [each for each in issues if "join" in each]
+    assert any("Line 2" in each_issue for each_issue in join_issues), (
+        f"introduced join separator must block at its new location, got: {join_issues}"
+    )

package/hooks/blocking/test_code_rules_enforcer_string_magic.py

@@ -232,3 +232,101 @@ def test_should_still_flag_literal_in_nested_function_body() -> None:
     assert len(issues) == 1, (
         f"Inner literal must be flagged exactly once (no duplicate from outer walk), got: {issues}"
     )
+
+
+def test_should_grandfather_unchanged_string_magic_in_wide_edit() -> None:
+    prior_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    proposed_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    # wide edit that leaves the magic string in place\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    magic_issues = [each for each in issues if "STRIPE_SECRET" in each]
+    assert magic_issues == [], (
+        f"unchanged enclosed string magic must be grandfathered, got: {magic_issues}"
+    )
+
+
+def test_should_block_new_string_magic_in_wide_edit() -> None:
+    prior_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ.get('missing', '')\n"
+    )
+    proposed_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    magic_issues = [each for each in issues if "STRIPE_SECRET" in each]
+    assert any("Line " in each_issue for each_issue in magic_issues), (
+        f"introduced string magic must block with a line locator, got: {magic_issues}"
+    )
+    assert any("STRIPE_SECRET" in each_issue for each_issue in magic_issues)
+
+
+def test_should_block_second_identical_string_magic_per_occurrence() -> None:
+    prior_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    proposed_fragment = (
+        "import os\n"
+        "\n"
+        "def fetch_secret() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+        "\n"
+        "def fetch_backup() -> str:\n"
+        "    return os.environ['STRIPE_SECRET']\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        proposed_fragment,
+        PRODUCTION_FILE_PATH,
+        prior_fragment,
+    )
+    magic_issues = [each for each in issues if "STRIPE_SECRET" in each]
+    assert len(magic_issues) == 1, (
+        f"exactly one new identical magic must block (per-occurrence), got: {magic_issues}"
+    )
+    assert any("Line 7" in each_issue for each_issue in magic_issues), (
+        f"second occurrence must keep proposed-fragment line, got: {magic_issues}"
+    )
+
+
+def test_should_surface_magic_when_gate_defers_scope_with_head_as_old() -> None:
+    source = (
+        "def compute() -> int:\n"
+        "    old_number = 9999\n"
+        "    return old_number\n"
+    )
+    issues = code_rules_enforcer.validate_content(
+        source,
+        PRODUCTION_FILE_PATH,
+        source,
+        defer_scope_to_caller=True,
+    )
+    assert any("9999" in each_issue for each_issue in issues), (
+        f"gate path must still surface whole-file magic when old_content equals content, "
+        f"got: {issues}"
+    )