claude-dev-env 1.83.0 → 1.85.0

package/hooks/blocking/code_rules_docstrings.py

@@ -53,6 +53,8 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_ZIPFILE_WRITE_MODE_VALUES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME,
+    DOCSTRING_NARRATIVE_LINE_JOIN_SEPARATOR,
+    DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT,
     DOCSTRING_REFERENCE_MARKER_WINDOW,
     DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN,
     DOCSTRING_RUNON_SENTENCE_WORD_LIMIT,
@@ -72,6 +74,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
     MAX_DOCSTRING_NO_NETWORK_CLAIM_ISSUES,
+    MAX_DOCSTRING_PROSE_WALL_ISSUES,
     MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
@@ -90,6 +93,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
+    MINIMUM_RANGE_ARGS_FOR_SPAN,
     MINIMUM_SIBLING_OCCURRENCES_FOR_SHARED_TOKEN,
     MINIMUM_TOKENS_FOR_DISPATCH_CALLEE,
     MINIMUM_TUPLE_MEMBERS_FOR_DOCSTRING_ENUMERATION,
@@ -2016,13 +2020,14 @@ def _documentable_docstrings_with_line(parsed_tree: ast.Module) -> list[tuple[in
 def check_docstring_cardinal_count_matches_constant_family(
     content: str, file_path: str
 ) -> list[str]:
-    """Flag a docstring cardinal count that under-names a referenced constant family.
+    """Flag a docstring cardinal count that differs from a referenced constant family.
 
     The drift this catches: a docstring states a cardinal count of an outcome
     family (``Covers the four outcome branches: ...``) and enumerates that
-    family's members in prose, while the module references more members of the
-    same ``UPPER_SNAKE`` constant family than the count names. The prose
-    under-describes the code — a reader trusts the count and the enumeration to
+    family's members in prose, while the module references a member set of the
+    same ``UPPER_SNAKE`` constant family whose size differs from the stated
+    count — above it and below it both trip. The prose
+    misdescribes the code — a reader trusts the count and the enumeration to
     be the full set, but the module imports and exercises an outcome the summary
     omits. The check binds only when the docstring states a cardinal beside an
     outcome noun, names two or more members of one referenced family, leaves at
@@ -2035,7 +2040,8 @@ def check_docstring_cardinal_count_matches_constant_family(
 
     Args:
         content: The source text to inspect.
-        file_path: The path the source will be written to, used for exemptions.
+        file_path: Accepted for the uniform check interface; the body does not
+            read it.
 
     Returns:
         One issue per docstring whose cardinal count and enumeration omit a
@@ -2470,12 +2476,12 @@ def _argument_prose_scopes_a_single_line(argument_prose: str) -> bool:
     )
 
 
-def _call_node_builds_two_argument_range(call_node: ast.Call) -> bool:
+def _call_node_builds_explicit_start_range(call_node: ast.Call) -> bool:
     callee = call_node.func
     return (
         isinstance(callee, ast.Name)
         and callee.id == "range"
-        and len(call_node.args) >= MINIMUM_TOKENS_FOR_DISPATCH_CALLEE
+        and len(call_node.args) >= MINIMUM_RANGE_ARGS_FOR_SPAN
     )
 
 
@@ -2487,7 +2493,7 @@ def _function_body_scopes_a_span_by_intersection(
     for each_node in ast.walk(function_node):
         if not isinstance(each_node, ast.Call):
             continue
-        if _call_node_builds_two_argument_range(each_node):
+        if _call_node_builds_explicit_start_range(each_node):
             builds_range_span = True
         if _call_callee_name(each_node) in ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES:
             calls_span_scoper = True
@@ -2507,11 +2513,12 @@ def check_docstring_args_single_line_scope_vs_span(content: str, file_path: str)
     is the deterministic slice of Category O6 docstring-vs-implementation drift
     for an Args single-line scope claim disagreeing with a span-intersection body.
 
-    An entry is left alone when its prose says "any line of" / "any line in" its
-    span, since that wording matches the span body. The body is judged a
-    span-intersection scoper only when it both builds a two-argument ``range(...)``
-    and calls a known span scoper, so a body that scopes by a single line never
-    trips the check. Hook infrastructure is in scope here — the import-sort gate
+    An entry is left alone when its prose says "any line of" / "any line in" /
+    "any of its lines" / "any span line" about its span, since that wording
+    matches the span body. The body is judged a span-intersection scoper only
+    when it both builds an explicit-start ``range(...)`` (two or more
+    arguments) and calls a known span scoper, so a body that scopes by a
+    single line never trips the check. Hook infrastructure is in scope here — the import-sort gate
     that carries this drift class is itself a hook — and test files are exempt.
 
     Args:
@@ -2562,14 +2569,71 @@ def _is_narrative_cut_header(stripped_line: str) -> bool:
     )
 
 
-def _docstring_narrative_text(docstring_text: str) -> str:
-    narrative_lines: list[str] = []
-    for each_line in docstring_text.splitlines():
-        stripped_line = each_line.strip()
+def _docstring_narrative_partition(docstring_text: str) -> tuple[list[str], bool]:
+    """Split a docstring narrative into its prose lines and whether it shows an example.
+
+    Walk the narrative up to the first ``Args:``/``Returns:`` cut header and sort
+    every line into one of two buckets::
+
+        Render the report so the reader sees how it ended.   <- prose line
+        A finished run versus an interrupted one::           <- prose line (opener)
+            theme_42 -- interrupted -> marked in-flight       -- indented example body
+            OK:   a clean run reads differently in the log    -- indented example body
+        The reader reads the final outcome at a glance.      <- prose line
+
+    A ``>>>`` doctest region and a ``::`` block with an indented body both count as
+    an illustration, so their lines never join the prose bucket. The caller reads
+    the prose count to size the wall and the flag to know whether an example is present.
+    """
+    prose_lines: list[str] = []
+    has_illustration = False
+    all_lines = docstring_text.splitlines()
+    total_lines = len(all_lines)
+    line_index = 0
+    while line_index < total_lines:
+        raw_line = all_lines[line_index]
+        stripped_line = raw_line.strip()
         if _is_narrative_cut_header(stripped_line):
             break
-        narrative_lines.append(stripped_line)
-    return " ".join(narrative_lines)
+        if stripped_line.startswith(">>>"):
+            has_illustration = True
+            line_index += 1
+            while line_index < total_lines:
+                inner_stripped = all_lines[line_index].strip()
+                if not inner_stripped or _is_narrative_cut_header(inner_stripped):
+                    break
+                line_index += 1
+            continue
+        if stripped_line.endswith("::"):
+            opener_indent = len(raw_line) - len(raw_line.lstrip())
+            probe_index = line_index + 1
+            has_indented_body = False
+            while probe_index < total_lines:
+                probe_raw = all_lines[probe_index]
+                probe_stripped = probe_raw.strip()
+                if not probe_stripped:
+                    probe_index += 1
+                    continue
+                probe_indent = len(probe_raw) - len(probe_raw.lstrip())
+                if probe_indent > opener_indent:
+                    has_indented_body = True
+                    probe_index += 1
+                    continue
+                break
+            if has_indented_body:
+                has_illustration = True
+                prose_lines.append(stripped_line)
+                line_index = probe_index
+                continue
+        if stripped_line:
+            prose_lines.append(stripped_line)
+        line_index += 1
+    return prose_lines, has_illustration
+
+
+def _docstring_narrative_text(docstring_text: str) -> str:
+    prose_lines, _has_illustration = _docstring_narrative_partition(docstring_text)
+    return DOCSTRING_NARRATIVE_LINE_JOIN_SEPARATOR.join(prose_lines)
 
 
 def _sentence_word_count(sentence_text: str) -> int:
@@ -2675,6 +2739,56 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
     return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
 
 
+def check_docstring_prose_wall_without_illustration(content: str, file_path: str) -> list[str]:
+    """Flag a summary that tells for many sentences and shows nothing.
+
+    A reader trusts the opening to paint a scene. A run of short sentences with
+    no worked example leaves the reader piecing that scene together alone::
+
+        A calm voyage ends well for every vessel.            <- one more line
+        A halted voyage marks the vessel it neared.          <- and another
+        ... more like these, no worked example ...           flag: a wall, no scene
+        A calm voyage versus a halted one::                  ok: a worked example
+            a lone vessel -- halted -> marked mid-voyage
+
+    Past the prose-line limit with no ``::`` listing and no ``>>>`` doctest, this
+    fires. A narrative that shows a worked example, or one at the limit, passes.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per summary that runs a wall of sentences with no worked
+        example, capped at the issue limit for the rule.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_line_number, each_label, each_docstring in _documentable_docstring_targets(
+        parsed_tree
+    ):
+        prose_lines, has_illustration = _docstring_narrative_partition(each_docstring)
+        if has_illustration:
+            continue
+        prose_line_count = len(prose_lines)
+        if prose_line_count <= DOCSTRING_NARRATIVE_PROSE_LINE_LIMIT:
+            continue
+        issues.append(
+            f"Line {each_line_number}: {each_label} summary runs {prose_line_count} "
+            "narrative lines with no worked example - show, don't tell: swap the wall for a "
+            "'::' listing (a sample input, an annotated outcome, ok/flag contrast rows) and "
+            "keep the narrative to a few short lines (plain-illustrative-docstrings)"
+        )
+        if len(issues) >= MAX_DOCSTRING_PROSE_WALL_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_PROSE_WALL_ISSUES]
+
+
 def _raises_section_text(docstring_text: str) -> str:
     docstring_lines = docstring_text.splitlines()
     raises_section_lines: list[str] = []

package/hooks/blocking/code_rules_enforcer.py

@@ -87,6 +87,7 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
     check_docstring_no_network_claim_with_metadata_access,
+    check_docstring_prose_wall_without_illustration,
     check_docstring_punctuation_mark_enumeration_coverage,
     check_docstring_raises_unraisable_largezipfile,
     check_docstring_returns_plural_cardinality,
@@ -351,6 +352,9 @@ def validate_content(
             check_class_docstring_names_public_methods(effective_content, file_path)
         )
         all_issues.extend(check_docstring_runon_sentence(effective_content, file_path))
+        all_issues.extend(
+            check_docstring_prose_wall_without_illustration(effective_content, file_path)
+        )
         all_issues.extend(
             check_module_docstring_names_public_checks(effective_content, file_path)
         )

package/hooks/blocking/code_rules_imports_logging.py

@@ -244,7 +244,8 @@ def check_import_block_sorted(
             give ruff the filename it needs for config discovery.
         all_changed_lines: Post-edit line numbers the current edit touched, or
             None to treat the whole file as in scope. When provided, a finding
-            blocks only when its block-anchor line is among the changed lines.
+            blocks only when any line of its block span is among the changed
+            lines.
         defer_scope_to_caller: When True, return every finding so the commit/push
             gate's ``Line N:`` partitioning scopes by added line.
 
@@ -813,9 +814,9 @@ def _naive_datetime_remediation(constructor_name: str) -> str:
     """Return the fix guidance for a specific naive datetime constructor.
 
     ``utcnow`` and ``utcfromtimestamp`` accept no ``tz`` argument, so each points
-    at its aware replacement (``datetime.now(tz=...)`` and
-    ``datetime.fromtimestamp(..., tz=...)``); ``fromtimestamp`` keeps its shape and
-    only needs a ``tz=`` argument.
+    at its aware replacement (``now(tz=...)`` and ``fromtimestamp(..., tz=...)``
+    on the same datetime class, whichever import form the call used);
+    ``fromtimestamp`` keeps its shape and only needs a ``tz=`` argument.
 
     Args:
         constructor_name: The naive constructor the call used.
@@ -824,9 +825,12 @@ def _naive_datetime_remediation(constructor_name: str) -> str:
         The remediation clause to embed in the emitted issue.
     """
     if constructor_name == NAIVE_DATETIME_UTCNOW_CONSTRUCTOR:
-        return "use datetime.now(tz=timezone.utc)"
+        return "replace utcnow() with now(tz=timezone.utc) on the same datetime class"
     if constructor_name == NAIVE_DATETIME_UTCFROMTIMESTAMP_CONSTRUCTOR:
-        return "use datetime.fromtimestamp(..., tz=timezone.utc)"
+        return (
+            "replace utcfromtimestamp(...) with fromtimestamp(..., tz=timezone.utc) "
+            "on the same datetime class"
+        )
     return "pass tz= (e.g. tz=timezone.utc)"
 
 

package/hooks/blocking/code_rules_magic_values.py

@@ -17,6 +17,7 @@ from code_rules_path_utils import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     _extract_fstring_literal_parts,
+    docstring_line_numbers,
     is_test_file,
 )
 
@@ -156,6 +157,7 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
 
     issues = []
     lines = content.split("\n")
+    all_docstring_line_numbers = docstring_line_numbers(content)
     is_inside_function = False
 
     number_pattern = re.compile(r"(?<![.\w])(\d+\.?\d*)(?![.\w])")
@@ -167,6 +169,9 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
         if not stripped:
             continue
 
+        if each_line_number in all_docstring_line_numbers:
+            continue
+
         if re.match(r"^(async\s+)?def\s+\w+", stripped):
             is_inside_function = True
             continue

package/hooks/blocking/code_rules_naming_collection.py

@@ -434,14 +434,21 @@ def _contradicting_polarity_pair(target_name: str, called_name: str) -> tuple[st
 
 
 def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]:
-    """Flag a boolean assignment whose target and callee assert opposite polarity.
-
-    Catches the self-contradicting statement ``is_inside_allowed =
-    _point_hits_any_forbidden(...)`` — a target name carrying one polarity token
-    (``allowed``) assigned directly from a single call whose callee name carries
-    the antonym token (``forbidden``). One side lies about the behavior, so the
-    reader cannot trust either name. Rename the callee to a neutral form that
-    reads truthfully at every call site.
+    """Flag an assignment whose target and callee assert opposite polarity.
+
+    ::
+
+        is_inside_allowed = _point_hits_any_forbidden(...)
+                 ^^^^^^^                    ^^^^^^^^^
+                 allowed         vs.        forbidden      ⚠ the two names clash
+        ok:   is_inside_allowed = _point_inside_allowed_region(...)
+        flag: is_inside_allowed = _point_hits_any_forbidden(...)
+
+    The target token and the callee token contradict each other, so the reader
+    cannot tell which name states the truth. Any single-name assignment from a
+    call is inspected — collections and counts included, not only booleans.
+    Rename the callee to a neutral form the two names agree on at every call
+    site.
     """
     if is_test_file(file_path):
         return []

package/hooks/blocking/code_rules_paired_test.py

@@ -164,8 +164,9 @@ def _stem_matched_test_path(module_path: Path) -> Path | None:
 
     Returns:
         The path of the first existing ``test_<stem>.py`` or ``<stem>_test.py``
-        file — beside the module or under an ancestor ``tests`` directory — or
-        None when the module has no dedicated test file.
+        file beside the module, or ``test_<stem>.py`` under an ancestor
+        ``tests`` directory — or None when the module has no dedicated test
+        file.
     """
     module_directory = module_path.parent
     module_stem = module_path.stem

package/hooks/blocking/code_rules_shared.py

@@ -273,6 +273,40 @@ def is_migration_file(file_path: str) -> bool:
     return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_MIGRATION_PATH_PATTERNS)
 
 
+def docstring_line_numbers(content: str) -> set[int]:
+    """Return every source line that sits inside a string-literal statement.
+
+    A diagram-first docstring often draws its point across several lines, and
+    those lines can hold a bare number (a row marker) or a contrast row
+    (``flag: is_ok = do_thing(...)``). Those are prose, not code, so a
+    line-based lint check that reads them as literals fires a false positive.
+    This walks the parsed source and collects the line numbers spanned by every
+    string-literal expression statement — module, class, and function
+    docstrings, plus any bare string statement — so those checks can skip them.
+    Unparseable source yields an empty set.
+
+    Args:
+        content: The Python source to scan.
+
+    Returns:
+        The 1-indexed line numbers that fall inside a string-literal statement.
+    """
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return set()
+    all_docstring_line_numbers: set[int] = set()
+    for each_node in ast.walk(parsed_tree):
+        if not (isinstance(each_node, ast.Expr) and _statement_is_docstring(each_node)):
+            continue
+        end_line_number = each_node.end_lineno
+        if end_line_number is None:
+            continue
+        for each_line_number in range(each_node.lineno, end_line_number + 1):
+            all_docstring_line_numbers.add(each_line_number)
+    return all_docstring_line_numbers
+
+
 def _build_parent_map(module_tree: ast.Module) -> dict[int, ast.AST]:
     """Map child node id() to its parent node for ancestor walking."""
     parent_by_child_id: dict[int, ast.AST] = {}

package/hooks/blocking/code_rules_string_magic.py

@@ -1,4 +1,4 @@
-"""Bare string-literal magic, inline literal-collection, inline tuple string-magic, and whitespace-indentation magic checks."""
+"""Bare string-literal magic, join-separator string magic, inline literal-collection, inline tuple string-magic, and whitespace-indentation magic checks."""
 
 import ast
 import re

package/hooks/blocking/code_rules_unused_imports.py

@@ -1,4 +1,4 @@
-"""Unused module-level import check and its import-range and type-checking-gate helpers."""
+"""Unused module-level import check and its import-range helpers."""
 
 import ast
 import sys
@@ -143,7 +143,7 @@ def check_unused_module_level_imports(
 
     When ``full_file_content`` is provided, ``content`` is treated as an Edit
     fragment containing the imports being added or replaced, while the
-    ``__all__`` / ``TYPE_CHECKING`` gate detection and reference scanning run
+    ``__all__`` gate detection and reference scanning run
     against ``full_file_content`` (the post-edit file as it will look once the
     Edit applies). This prevents false-positive flags on imports added in the
     same Edit as their consumers.

package/hooks/blocking/duplicate_rmtree_helper_blocker.py

@@ -72,10 +72,10 @@ def path_is_exempt(file_path: str) -> bool:
     Returns:
         True when the path's basename is the canonical shared-helper home, an
         rmtree-blocker hook source, one of the existing in-repo definition sites
-        (session_env_cleanup.py, _md_to_html_blocker_test_support.py,
-        teardown_worktrees.py), or a test file. A definition there is intentional.
-        Basename equality (not substring containment) prevents a sibling whose name
-        merely contains an exempt fragment from bypassing the block.
+        (session_env_cleanup.py, teardown_worktrees.py), or a test file. A
+        definition there is intentional. Basename equality (not substring
+        containment) prevents a sibling whose name merely contains an exempt
+        fragment from bypassing the block.
     """
     normalized_path = file_path.replace("\\", "/")
     file_name = normalized_path.rsplit("/", 1)[-1]

package/hooks/blocking/test_code_rules_enforcer_docstring_args_span_scope.py

@@ -75,6 +75,35 @@ def test_flags_anchor_line_scope_against_span_intersection_body() -> None:
     assert "all_changed_lines" in issues[0]
 
 
+def test_flags_single_line_scope_against_stepped_range_span_body() -> None:
+    content = (
+        "def check_import_block_sorted(\n"
+        "    content: str, file_path: str, all_changed_lines: set[int] | None\n"
+        ") -> list[str]:\n"
+        '    """Flag an unsorted import block scoped to the changed lines.\n'
+        "\n"
+        "    Args:\n"
+        "        content: The full file content the write would leave on disk.\n"
+        "        file_path: The destination path used to gate by extension.\n"
+        "        all_changed_lines: Post-edit line numbers, or None. When provided,\n"
+        "            a finding blocks only when its block-anchor line is among the\n"
+        "            changed lines.\n"
+        "\n"
+        "    Returns:\n"
+        "        One issue string per detected finding.\n"
+        '    """\n'
+        "    span_range = range(line_number, block_end_line_number + 1, 1)\n"
+        "    all_violations.append((span_range, message))\n"
+        "    return _scope_violations_to_changed_lines(\n"
+        "        all_violations, all_changed_lines, defer_scope_to_caller\n"
+        "    )\n"
+    )
+    issues = check_docstring_args_single_line_scope_vs_span(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "check_import_block_sorted" in issues[0]
+    assert "all_changed_lines" in issues[0]
+
+
 def test_flags_the_line_is_among_phrasing() -> None:
     content = (
         "def check_block(\n"