claude-dev-env 1.77.0 → 1.78.0

package/hooks/blocking/code_rules_docstrings.py

@@ -34,32 +34,46 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_RUNON_JOINER_MARKERS,
     ALL_GENERIC_CHECK_NAME_TOKENS,
     ALL_NAMING_CONVENTION_DESCRIPTOR_TOKENS,
+    ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES,
     DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_REFERENCE_MARKER_WINDOW,
     DOCSTRING_RUNON_SENTENCE_BOUNDARY_PATTERN,
     DOCSTRING_RUNON_SENTENCE_WORD_LIMIT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
     MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
+    MAX_COMPANION_MODULE_RESOLUTION_DEPTH,
+    PYTHON_MODULE_FILE_SUFFIX,
+    WORD_BOUNDARY_REGEX,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
     MAX_DOCSTRING_CARDINAL_FAMILY_ISSUES,
     MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
     MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES,
+    MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
     MAX_DOCSTRING_RUNON_SENTENCE_ISSUES,
     ALL_DOCSTRING_SINGLE_LINE_SCOPE_PHRASES,
     ALL_DOCSTRING_SPAN_RANGE_BODY_CALLEE_NAMES,
     ALL_DOCSTRING_SPAN_SCOPE_OVERRIDE_PHRASES,
     MAX_DOCSTRING_ARGS_SPAN_SCOPE_ISSUES,
+    ALL_ZIPFILE_WRITE_MODE_VALUES,
+    DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME,
+    MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
     MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
+    ZIPFILE_ALLOW_ZIP64_KEYWORD,
+    ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX,
+    ZIPFILE_MODE_KEYWORD,
+    ZIPFILE_MODE_POSITIONAL_INDEX,
+    ZIPFILE_WRITER_CLASS_NAME,
     MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES,
     MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES,
     MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES,
     MINIMUM_CONSTANT_FAMILY_MEMBERS_FOR_CARDINAL_CHECK,
     MINIMUM_DOCSTRING_FAMILY_OVERLAP_FOR_CARDINAL_CHECK,
     MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK,
+    MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
     MINIMUM_TOKENS_FOR_DISPATCH_CALLEE,
@@ -1024,6 +1038,203 @@ def check_docstring_tuple_enumeration_match(content: str, file_path: str) -> lis
     return issues[:MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES]
 
 
+def _known_glyph_marker_members(
+    sequence_node: ast.Tuple | ast.List,
+) -> frozenset[str] | None:
+    normalized_glyphs: set[str] = set()
+    for each_element in sequence_node.elts:
+        if not (
+            isinstance(each_element, ast.Constant)
+            and isinstance(each_element.value, str)
+        ):
+            return None
+        normalized_glyph = each_element.value.strip()
+        if normalized_glyph not in ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES:
+            return None
+        normalized_glyphs.add(normalized_glyph)
+    return frozenset(normalized_glyphs)
+
+
+def _assignment_targets_and_sequence(
+    statement: ast.stmt,
+) -> tuple[list[str], ast.Tuple | ast.List | None]:
+    if isinstance(statement, ast.Assign) and isinstance(
+        statement.value, (ast.Tuple, ast.List)
+    ):
+        plain_target_names = [
+            each_target.id
+            for each_target in statement.targets
+            if isinstance(each_target, ast.Name)
+        ]
+        return plain_target_names, statement.value
+    if (
+        isinstance(statement, ast.AnnAssign)
+        and isinstance(statement.target, ast.Name)
+        and isinstance(statement.value, (ast.Tuple, ast.List))
+    ):
+        return [statement.target.id], statement.value
+    return [], None
+
+
+def _module_glyph_marker_tuples(parsed_tree: ast.Module) -> dict[str, frozenset[str]]:
+    glyphs_by_constant: dict[str, frozenset[str]] = {}
+    for each_statement in parsed_tree.body:
+        target_names, sequence_node = _assignment_targets_and_sequence(each_statement)
+        if sequence_node is None:
+            continue
+        marker_glyphs = _known_glyph_marker_members(sequence_node)
+        if marker_glyphs is None:
+            continue
+        if len(marker_glyphs) < MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION:
+            continue
+        for each_target_name in target_names:
+            glyphs_by_constant[each_target_name] = marker_glyphs
+    return glyphs_by_constant
+
+
+def _companion_module_file(dotted_module: str, file_path: str) -> Path | None:
+    relative_module_path = Path(*dotted_module.split(".")).with_suffix(
+        PYTHON_MODULE_FILE_SUFFIX
+    )
+    file_directory = Path(file_path).parent
+    candidate_roots = [file_directory, *file_directory.parents]
+    for each_root in candidate_roots[:MAX_COMPANION_MODULE_RESOLUTION_DEPTH]:
+        candidate_path = each_root / relative_module_path
+        if candidate_path.is_file():
+            return candidate_path
+    return None
+
+
+def _companion_glyph_marker_tuples(companion_path: Path) -> dict[str, frozenset[str]]:
+    try:
+        companion_source = companion_path.read_text(encoding="utf-8")
+        companion_tree = ast.parse(companion_source)
+    except (OSError, ValueError, SyntaxError):
+        return {}
+    return _module_glyph_marker_tuples(companion_tree)
+
+
+def _import_brings_upper_snake_name(import_node: ast.ImportFrom) -> bool:
+    return any(
+        ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(each_alias.name)
+        for each_alias in import_node.names
+    )
+
+
+def _imported_glyph_marker_tuples(
+    parsed_tree: ast.Module, file_path: str
+) -> dict[str, frozenset[str]]:
+    glyphs_by_imported_name: dict[str, frozenset[str]] = {}
+    for each_statement in parsed_tree.body:
+        if not isinstance(each_statement, ast.ImportFrom):
+            continue
+        if not each_statement.module:
+            continue
+        if not _import_brings_upper_snake_name(each_statement):
+            continue
+        companion_path = _companion_module_file(each_statement.module, file_path)
+        if companion_path is None:
+            continue
+        companion_tuples = _companion_glyph_marker_tuples(companion_path)
+        for each_alias in each_statement.names:
+            if each_alias.name not in companion_tuples:
+                continue
+            imported_name = each_alias.asname or each_alias.name
+            glyphs_by_imported_name[imported_name] = companion_tuples[each_alias.name]
+    return glyphs_by_imported_name
+
+
+def _docstring_names_mark_glyph(docstring_text: str, normalized_glyph: str) -> bool:
+    lowercased_docstring = docstring_text.lower()
+    for each_name in ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES[normalized_glyph]:
+        boundary_wrapped_name = (
+            WORD_BOUNDARY_REGEX + re.escape(each_name) + WORD_BOUNDARY_REGEX
+        )
+        if re.search(boundary_wrapped_name, lowercased_docstring):
+            return True
+    return False
+
+
+def _marks_named_in_docstring(
+    docstring_text: str, all_marker_glyphs: frozenset[str]
+) -> set[str]:
+    return {
+        each_glyph
+        for each_glyph in all_marker_glyphs
+        if _docstring_names_mark_glyph(docstring_text, each_glyph)
+    }
+
+
+def _text_names_multiple_marks(content_text: str) -> bool:
+    all_known_glyphs = frozenset(ALL_PUNCTUATION_MARK_GLYPH_PROSE_NAMES)
+    named_glyphs = _marks_named_in_docstring(content_text, all_known_glyphs)
+    return len(named_glyphs) >= MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION
+
+
+def check_docstring_punctuation_mark_enumeration_coverage(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring that names some marks of a glyph tuple but omits one.
+
+    A module reads a tuple of punctuation-mark glyphs as its detection set. The
+    tuple is defined in the module or imported from a companion module beside it.
+    A docstring then enumerates those marks by their English names. When the
+    prose names a closed set of marks but leaves one the tuple holds unnamed, a
+    reader trusts the enumeration and believes an active mark never triggers the
+    check. This is the shape that appears when a glyph joins the tuple while the
+    prose enumeration stays as it was.
+
+    The check binds only when a docstring names two or more marks of one tuple. A
+    docstring that mentions a single mark, names every mark, or describes
+    unrelated punctuation is left alone. This is the deterministic glyph-prose
+    slice of Category O6 docstring-prose-vs-implementation drift, the companion
+    to check_docstring_tuple_enumeration_match for glyph members named in prose
+    rather than identifier members named in inline code. It covers hook
+    infrastructure, where the affected detection tuples live.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per docstring whose mark enumeration omits a glyph the tuple it
+        describes holds, capped at the module limit.
+    """
+    if is_strict_test_file(file_path):
+        return []
+    if not _text_names_multiple_marks(content):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    glyphs_by_constant = {
+        **_module_glyph_marker_tuples(parsed_tree),
+        **_imported_glyph_marker_tuples(parsed_tree, file_path),
+    }
+    if not glyphs_by_constant:
+        return []
+    issues: list[str] = []
+    for each_line, each_docstring in _documentable_docstrings_with_line(parsed_tree):
+        for each_constant_name in sorted(glyphs_by_constant):
+            marker_glyphs = glyphs_by_constant[each_constant_name]
+            named_glyphs = _marks_named_in_docstring(each_docstring, marker_glyphs)
+            if len(named_glyphs) < MINIMUM_NAMED_MARKS_FOR_PROSE_ENUMERATION:
+                continue
+            omitted_glyphs = marker_glyphs - named_glyphs
+            if not omitted_glyphs:
+                continue
+            issues.append(
+                f"Line {each_line}: docstring names {sorted(named_glyphs)} from "
+                f"{each_constant_name} but omits {sorted(omitted_glyphs)} — name every "
+                "mark the tuple holds so the enumeration matches the detection set "
+                "(Category O6 docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES:
+                return issues[:MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES]
+    return issues[:MAX_DOCSTRING_MARK_GLYPH_ENUMERATION_ISSUES]
+
+
 def _returns_section_text(docstring_text: str) -> str:
     docstring_lines = docstring_text.splitlines()
     returns_section_lines: list[str] = []
@@ -1836,3 +2047,144 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
         if len(issues) >= MAX_DOCSTRING_RUNON_SENTENCE_ISSUES:
             break
     return issues[:MAX_DOCSTRING_RUNON_SENTENCE_ISSUES]
+
+
+def _raises_section_text(docstring_text: str) -> str:
+    docstring_lines = docstring_text.splitlines()
+    raises_section_lines: list[str] = []
+    inside_raises_section = False
+    for each_line in docstring_lines:
+        stripped_line = each_line.strip()
+        if stripped_line == "Raises:":
+            inside_raises_section = True
+            continue
+        if not inside_raises_section:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        raises_section_lines.append(stripped_line)
+    return " ".join(raises_section_lines)
+
+
+def _call_argument_by_keyword_or_position(
+    call_node: ast.Call, keyword_name: str, positional_index: int
+) -> ast.expr | None:
+    for each_keyword in call_node.keywords:
+        if each_keyword.arg == keyword_name:
+            return each_keyword.value
+    if positional_index >= len(call_node.args):
+        return None
+    if any(
+        isinstance(each_argument, ast.Starred)
+        for each_argument in call_node.args[: positional_index + 1]
+    ):
+        return None
+    return call_node.args[positional_index]
+
+
+def _call_opens_zipfile_write_mode_writer(call_node: ast.Call) -> bool:
+    callee = call_node.func
+    if isinstance(callee, ast.Attribute):
+        callee_name = callee.attr
+    elif isinstance(callee, ast.Name):
+        callee_name = callee.id
+    else:
+        return False
+    if callee_name != ZIPFILE_WRITER_CLASS_NAME:
+        return False
+    mode_argument = _call_argument_by_keyword_or_position(
+        call_node, ZIPFILE_MODE_KEYWORD, ZIPFILE_MODE_POSITIONAL_INDEX
+    )
+    return (
+        isinstance(mode_argument, ast.Constant)
+        and mode_argument.value in ALL_ZIPFILE_WRITE_MODE_VALUES
+    )
+
+
+def _zipfile_writer_forbids_zip64(call_node: ast.Call) -> bool:
+    allow_zip64_argument = _call_argument_by_keyword_or_position(
+        call_node, ZIPFILE_ALLOW_ZIP64_KEYWORD, ZIPFILE_ALLOW_ZIP64_POSITIONAL_INDEX
+    )
+    return (
+        isinstance(allow_zip64_argument, ast.Constant)
+        and allow_zip64_argument.value is False
+    )
+
+
+def _function_documents_unraisable_largezipfile(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    docstring_text: str,
+) -> bool:
+    if DOCSTRING_LARGE_ZIP_FILE_EXCEPTION_NAME not in _raises_section_text(docstring_text):
+        return False
+    write_mode_writers = [
+        each_descendant
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+        if isinstance(each_descendant, ast.Call)
+        and _call_opens_zipfile_write_mode_writer(each_descendant)
+    ]
+    if not write_mode_writers:
+        return False
+    return not any(
+        _zipfile_writer_forbids_zip64(each_writer) for each_writer in write_mode_writers
+    )
+
+
+def check_docstring_raises_unraisable_largezipfile(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a Raises clause naming LargeZipFile over a default-ZIP64 writer.
+
+    The drift this catches: a function whose docstring Raises clause lists
+    ``zipfile.LargeZipFile`` while the function opens its ``zipfile.ZipFile``
+    writer in a write mode (``w``/``a``/``x``) with ``allowZip64`` left at its
+    default of True. The stdlib raises ``LargeZipFile`` only when an entry needs
+    ZIP64 AND ``allowZip64`` is False; with ZIP64 permitted the writer
+    transparently uses it and never raises. The Raises entry then documents an
+    exception the body cannot produce, so a caller guarding ``LargeZipFile`` on
+    the strength of the docstring guards an unreachable path. This is the
+    deterministic slice of Category O6 docstring-prose-vs-implementation drift
+    where a writer opened with default ZIP64 disagrees with a LargeZipFile
+    Raises clause.
+
+    The check binds only when the function opens at least one write-mode
+    ``ZipFile`` and every such writer permits ZIP64, so a function that forbids
+    ZIP64 on any writer (``allowZip64=False``, by keyword or position), a
+    read-only open, and a function that opens no writer — where the exception may
+    propagate from a callee — are all left alone.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose LargeZipFile Raises clause names an
+        unreachable exception, capped at the module limit.
+    """
+    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_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        if not _function_documents_unraisable_largezipfile(each_node, docstring_text):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring Raises lists "
+            "zipfile.LargeZipFile, but the function opens its ZipFile writer with ZIP64 "
+            "permitted (allowZip64 defaults to True) — LargeZipFile raises only when "
+            "allowZip64 is False, so drop the entry or pass allowZip64=False "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_RAISES_LARGEZIPFILE_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -64,6 +64,9 @@ from code_rules_dead_dataclass_field import (  # noqa: E402
 from code_rules_dead_module_constant import (  # noqa: E402
     check_dead_module_constants,
 )
+from code_rules_dead_split_branch import (  # noqa: E402
+    check_dead_split_truthiness_branch,
+)
 from code_rules_docstrings import (  # noqa: E402
     check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
@@ -74,6 +77,8 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
+    check_docstring_punctuation_mark_enumeration_coverage,
+    check_docstring_raises_unraisable_largezipfile,
     check_docstring_returns_plural_cardinality,
     check_docstring_runon_sentence,
     check_docstring_step_enumeration_dispatch_coverage,
@@ -116,6 +121,9 @@ from code_rules_optional_params import (  # noqa: E402
 from code_rules_orphan_css_class import (  # noqa: E402
     check_orphan_css_classes,
 )
+from code_rules_paired_test import (  # noqa: E402
+    check_public_function_missing_paired_test,
+)
 from code_rules_paths_syspath import (  # noqa: E402
     check_hardcoded_user_paths,
     check_sys_path_insert_deduplication_guard,
@@ -131,6 +139,7 @@ from code_rules_string_magic import (  # noqa: E402
     check_inline_literal_collections,
     check_inline_tuple_string_magic,
     check_string_literal_magic,
+    check_whitespace_indentation_magic,
 )
 from code_rules_test_assertions import (  # noqa: E402
     check_constant_equality_tests,
@@ -305,6 +314,11 @@ def validate_content(
         all_issues.extend(
             check_docstring_tuple_enumeration_match(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_punctuation_mark_enumeration_coverage(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_step_enumeration_dispatch_coverage(
                 effective_content, file_path
@@ -313,6 +327,9 @@ def validate_content(
         all_issues.extend(
             check_docstring_returns_plural_cardinality(effective_content, file_path)
         )
+        all_issues.extend(
+            check_docstring_raises_unraisable_largezipfile(effective_content, file_path)
+        )
         all_issues.extend(
             check_docstring_cardinal_count_matches_constant_family(
                 effective_content, file_path
@@ -373,6 +390,7 @@ def validate_content(
         all_issues.extend(
             check_dead_module_constants(content, file_path, full_file_content)
         )
+        all_issues.extend(check_dead_split_truthiness_branch(content, file_path))
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_known_pytest_fixture_annotations(content, file_path))
@@ -388,10 +406,19 @@ def validate_content(
                 defer_scope_to_caller,
             )
         )
+        all_issues.extend(
+            check_public_function_missing_paired_test(
+                effective_content,
+                file_path,
+                all_changed_lines,
+                defer_scope_to_caller,
+            )
+        )
         all_issues.extend(check_loop_variable_naming(content, file_path))
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
         all_issues.extend(check_string_literal_magic(content, file_path))
+        all_issues.extend(check_whitespace_indentation_magic(content, file_path))
         all_issues.extend(check_orphan_css_classes(effective_content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)