claude-dev-env 1.57.2 → 1.59.0

package/hooks/blocking/code_rules_annotations_length.py

@@ -13,6 +13,7 @@ if _hooks_directory not in sys.path:
 
 from code_rules_shared import (  # noqa: E402
     _collect_annotated_arguments,
+    _collect_fixture_injection_arguments,
     _definition_docstring_line_span,
     _function_definition_line_span,
     _scope_violations_to_changed_lines,
@@ -24,8 +25,10 @@ from code_rules_shared import (  # noqa: E402
 
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_SELF_AND_CLS_PARAMETER_NAMES,
+    ANNOTATION_BY_PYTEST_FIXTURE,
     FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX,
     FUNCTION_LENGTH_BLOCKING_THRESHOLD,
+    KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX,
 )
 
 
@@ -52,6 +55,156 @@ def check_parameter_annotations(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _is_pytest_fixture_injection_site(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when a function node is a valid pytest fixture injection site.
+
+    A function qualifies as a fixture injection site when either its name begins
+    with the ``test`` prefix (matching pytest's default ``python_functions = test*``
+    collection rule) or it carries a ``@pytest.fixture`` / ``@fixture`` decorator,
+    with or without call arguments.  Ordinary helper functions that happen to share
+    a parameter name with a known pytest fixture are excluded by this predicate so
+    that ``check_known_pytest_fixture_annotations`` only enforces annotation
+    requirements on the functions where pytest actually performs fixture injection.
+
+    Args:
+        node: The function definition AST node to inspect.
+
+    Returns:
+        True when the node is a pytest test function or a fixture-decorated
+        function; False otherwise.
+    """
+    if node.name.startswith("test"):
+        return True
+    for each_decorator in node.decorator_list:
+        unwrapped = each_decorator.func if isinstance(each_decorator, ast.Call) else each_decorator
+        if isinstance(unwrapped, ast.Name) and unwrapped.id == "fixture":
+            return True
+        if isinstance(unwrapped, ast.Attribute) and unwrapped.attr == "fixture":
+            return True
+    return False
+
+
+def _normalize_fixture_annotation_text(annotation_text: str) -> str:
+    """Strip forward-reference string quoting from an unparsed annotation.
+
+    ``ast.unparse`` renders a forward-reference annotation such as
+    ``tmp_path: "Path"`` as the quoted literal ``'Path'``. Removing the
+    surrounding quotes recovers the bare type name so the quoted spelling
+    compares equal to its unquoted form.
+
+    Args:
+        annotation_text: The annotation as rendered by ``ast.unparse``.
+
+    Returns:
+        The annotation text with any single surrounding quote pair removed.
+    """
+    if len(annotation_text) >= 2 and annotation_text[0] in {'"', "'"}:
+        if annotation_text[-1] == annotation_text[0]:
+            return annotation_text[1:-1]
+    return annotation_text
+
+
+def _fixture_annotation_matches_expected(
+    actual_annotation: str, expected_annotation: str
+) -> bool:
+    """Return True when an annotation matches its fixture's documented type.
+
+    The match accepts every equally-correct spelling of the documented type:
+    the exact text, a forward-reference string form, and either the bare
+    attribute tail or the fully-qualified dotted form. Both ``tmp_path: Path``
+    and ``tmp_path: pathlib.Path`` satisfy an expected ``Path``, and both
+    ``monkeypatch: pytest.MonkeyPatch`` and ``monkeypatch: MonkeyPatch``
+    satisfy an expected ``pytest.MonkeyPatch``.
+
+    Args:
+        actual_annotation: The annotation as rendered by ``ast.unparse``.
+        expected_annotation: The fixture's single documented type spelling.
+
+    Returns:
+        True when the actual annotation is an accepted spelling of the
+        expected type; False otherwise.
+    """
+    normalized_actual = _normalize_fixture_annotation_text(actual_annotation)
+    if normalized_actual == expected_annotation:
+        return True
+    return normalized_actual.rsplit(".", 1)[-1] == expected_annotation.rsplit(
+        ".", 1
+    )[-1]
+
+
+def check_known_pytest_fixture_annotations(content: str, file_path: str) -> list[str]:
+    """Flag well-known pytest fixture parameters lacking their type annotation.
+
+    The broad parameter-annotation rule exempts test files, so an ordinary
+    test parameter never needs a type hint. This narrower check restores
+    enforcement for exactly the pytest builtin fixtures whose injected type is
+    fixed and documented — ``tmp_path: Path``, ``monkeypatch:
+    pytest.MonkeyPatch``, and the rest of
+    ``ANNOTATION_BY_PYTEST_FIXTURE``. For these names the
+    correct annotation is unambiguous, so requiring it costs the author one
+    token and removes a recurring class of reviewer noise on test fixtures.
+    A non-test file produces no findings here: the broad check already covers
+    every parameter outside test files.
+
+    A known fixture parameter is flagged both when it carries no annotation and
+    when its annotation source differs from the fixture's single documented
+    type, so ``tmp_path: str`` is flagged exactly like ``tmp_path``. Only the
+    named injection slots pytest actually fills — undefaulted
+    positional-or-keyword and keyword-only parameters — are inspected. A
+    positional-only parameter is skipped because pytest passes fixtures by
+    keyword and can never bind one positionally; a defaulted parameter is
+    skipped because pytest leaves its default in place rather than injecting a
+    fixture; and a ``*args`` or ``**kwargs`` parameter that happens to share a
+    fixture name is never a fixture injection.
+
+    Args:
+        content: The Python source to analyze.
+        file_path: The path of the file being checked.
+
+    Returns:
+        One blocking issue per known fixture injection parameter whose
+        annotation is missing or differs from its single documented type,
+        naming the parameter and its expected type.
+    """
+    if not is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not _is_pytest_fixture_injection_site(each_node):
+            continue
+        for each_arg in _collect_fixture_injection_arguments(each_node):
+            expected_annotation = ANNOTATION_BY_PYTEST_FIXTURE.get(
+                each_arg.arg
+            )
+            if expected_annotation is None:
+                continue
+            actual_annotation = (
+                ast.unparse(each_arg.annotation)
+                if each_arg.annotation is not None
+                else None
+            )
+            if actual_annotation is not None and _fixture_annotation_matches_expected(
+                actual_annotation, expected_annotation
+            ):
+                continue
+            issues.append(
+                f"Line {each_arg.lineno}: parameter {each_arg.arg!r} on "
+                f"{each_node.name!r} - {KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX} "
+                f"(annotate as {expected_annotation!r})"
+            )
+    return issues
+
+
 def check_return_annotations(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []

package/hooks/blocking/code_rules_dead_dataclass_field.py

@@ -0,0 +1,319 @@
+"""Dead dataclass-field check: a @dataclass field assigned but never read in the same file."""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    is_migration_file,
+    is_test_file,
+)
+
+from hooks_constants.dead_dataclass_field_constants import (  # noqa: E402
+    ALL_DATACLASS_DECORATOR_NAMES,
+    ALL_WHOLE_INSTANCE_STRINGIFY_NAMES,
+    ATTRGETTER_FUNCTION_NAME,
+    CLASSVAR_ANNOTATION_NAME,
+    DEAD_DATACLASS_FIELD_GUIDANCE,
+    GETATTR_FUNCTION_NAME,
+    GETATTR_NAME_ARGUMENT_MINIMUM,
+    MAX_DEAD_DATACLASS_FIELD_ISSUES,
+    ALL_REFLECTIVE_FIELD_CONSUMER_NAMES,
+    WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME,
+)
+
+
+def _decorator_calls_dataclass(decorator_node: ast.expr) -> bool:
+    """Return whether a decorator expression applies @dataclass (bare or called)."""
+    target_node = (
+        decorator_node.func if isinstance(decorator_node, ast.Call) else decorator_node
+    )
+    if isinstance(target_node, ast.Name):
+        return target_node.id in ALL_DATACLASS_DECORATOR_NAMES
+    if isinstance(target_node, ast.Attribute):
+        return target_node.attr in ALL_DATACLASS_DECORATOR_NAMES
+    return False
+
+
+def _is_dataclass(class_node: ast.ClassDef) -> bool:
+    return any(
+        _decorator_calls_dataclass(each_decorator)
+        for each_decorator in class_node.decorator_list
+    )
+
+
+def _annotation_is_classvar(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Name):
+        return annotation_node.id == CLASSVAR_ANNOTATION_NAME
+    if isinstance(annotation_node, ast.Attribute):
+        return annotation_node.attr == CLASSVAR_ANNOTATION_NAME
+    if isinstance(annotation_node, ast.Subscript):
+        return _annotation_is_classvar(annotation_node.value)
+    return False
+
+
+def _dataclass_field_definitions(class_node: ast.ClassDef) -> list[tuple[str, int]]:
+    """Return (field_name, line) for each instance field declared in a dataclass body."""
+    fields: list[tuple[str, int]] = []
+    for each_statement in class_node.body:
+        if not isinstance(each_statement, ast.AnnAssign):
+            continue
+        if not isinstance(each_statement.target, ast.Name):
+            continue
+        if _annotation_is_classvar(each_statement.annotation):
+            continue
+        fields.append((each_statement.target.id, each_statement.lineno))
+    return fields
+
+
+def _string_constant_literal(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _dynamic_access_names(tree: ast.Module) -> tuple[set[str], bool]:
+    """Return literal attribute-name reads and whether the check must be suppressed.
+
+    Walks every ``getattr(obj, "name")`` and ``operator.attrgetter("a", "b")``
+    call, contributing each literal string name as a read attribute name —
+    ``getattr`` names its attribute in the second positional argument while
+    ``attrgetter`` names one attribute per positional argument. A non-literal
+    name argument, or any reflective whole-instance consumer (``asdict``,
+    ``astuple``, ``fields``, ``replace``, ``vars``) that reads every field at
+    once, means a field cannot be proven unread, so the boolean signals the
+    caller to suppress the check for the whole file.
+    """
+    literal_names: set[str] = set()
+    should_suppress_check = False
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Call):
+            continue
+        function_node = each_node.func
+        function_name = None
+        if isinstance(function_node, ast.Name):
+            function_name = function_node.id
+        elif isinstance(function_node, ast.Attribute):
+            function_name = function_node.attr
+        if function_name in ALL_REFLECTIVE_FIELD_CONSUMER_NAMES:
+            should_suppress_check = True
+            continue
+        if function_name not in {GETATTR_FUNCTION_NAME, ATTRGETTER_FUNCTION_NAME}:
+            continue
+        string_arguments = [
+            argument
+            for argument in each_node.args
+            if not isinstance(argument, ast.Starred)
+        ]
+        if function_name == GETATTR_FUNCTION_NAME:
+            name_arguments = (
+                [string_arguments[1]]
+                if len(string_arguments) >= GETATTR_NAME_ARGUMENT_MINIMUM
+                else []
+            )
+        else:
+            name_arguments = string_arguments
+        if not name_arguments:
+            should_suppress_check = True
+            continue
+        for each_name_argument in name_arguments:
+            literal_name = _string_constant_literal(each_name_argument)
+            if literal_name is None:
+                should_suppress_check = True
+            else:
+                literal_names.add(literal_name)
+    return literal_names, should_suppress_check
+
+
+def _augmented_assignment_attribute_names(tree: ast.Module) -> set[str]:
+    """Return attribute names that an augmented assignment reads before writing.
+
+    ``obj.field += value`` parses to an ``ast.Attribute`` target in Store
+    context, yet ``+=`` reads the current attribute value before storing the
+    result, so the target attribute counts as a read.
+    """
+    augmented_read_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.AugAssign):
+            continue
+        if isinstance(each_node.target, ast.Attribute):
+            augmented_read_names.add(each_node.target.attr)
+    return augmented_read_names
+
+
+def _attribute_read_names(tree: ast.Module) -> tuple[set[str], bool]:
+    """Return literal attribute-name reads and whether the check must be suppressed.
+
+    Walks every attribute read (Load context) and every augmented-assignment
+    target in the module, contributing each attribute name as a read name —
+    ``obj.field += value`` reads ``field`` before writing it. A read of
+    ``__dict__`` consumes every field of an instance at once, so it cannot prove
+    any single field unread and the boolean signals the caller to suppress the
+    check for the whole file.
+    """
+    read_names: set[str] = _augmented_assignment_attribute_names(tree)
+    should_suppress_check = False
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.Attribute) or not isinstance(
+            each_node.ctx, ast.Load
+        ):
+            continue
+        if each_node.attr == WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME:
+            should_suppress_check = True
+            continue
+        read_names.add(each_node.attr)
+    return read_names, should_suppress_check
+
+
+def _match_pattern_attribute_names(tree: ast.Module) -> set[str]:
+    """Return field names that a class pattern reads in a ``match`` statement.
+
+    A class pattern ``case Row(url=found):`` reads the ``url`` field through
+    ``ast.MatchClass.kwd_attrs``, so each keyword-pattern attribute name counts
+    as a read name even though it never appears as an attribute access.
+    """
+    matched_names: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.MatchClass):
+            matched_names.update(each_node.kwd_attrs)
+    return matched_names
+
+
+def _exported_names(tree: ast.Module) -> set[str]:
+    """Return names listed in a module-level ``__all__`` literal."""
+    exported: set[str] = set()
+    for each_node in tree.body:
+        if not isinstance(each_node, ast.Assign):
+            continue
+        targets_all = any(
+            isinstance(each_target, ast.Name) and each_target.id == "__all__"
+            for each_target in each_node.targets
+        )
+        if not targets_all:
+            continue
+        if isinstance(each_node.value, (ast.List, ast.Tuple, ast.Set)):
+            for each_element in each_node.value.elts:
+                literal_name = _string_constant_literal(each_element)
+                if literal_name is not None:
+                    exported.add(literal_name)
+    return exported
+
+
+def _constructed_class_names(tree: ast.Module) -> set[str]:
+    """Return names of classes instantiated by a direct call anywhere in the module."""
+    constructed: set[str] = set()
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Call) and isinstance(each_node.func, ast.Name):
+            constructed.add(each_node.func.id)
+    return constructed
+
+
+def _is_whole_instance_stringify_call(node: ast.AST) -> bool:
+    """Return whether a call stringifies a whole instance via ``str``/``repr``/``format``."""
+    if not isinstance(node, ast.Call):
+        return False
+    function_node = node.func
+    if isinstance(function_node, ast.Name):
+        return function_node.id in ALL_WHOLE_INSTANCE_STRINGIFY_NAMES
+    if isinstance(function_node, ast.Attribute):
+        return function_node.attr in ALL_WHOLE_INSTANCE_STRINGIFY_NAMES
+    return False
+
+
+def _uses_dataclass_dunder_field_reads(tree: ast.Module) -> bool:
+    """Return whether the file relies on auto-generated dataclass dunders to read fields.
+
+    ``@dataclass`` synthesizes ``__eq__`` (and ``__lt__``/``__hash__`` under
+    ``order``/``frozen``) plus the always-present ``__repr__``, each of which
+    reads every field without naming it as an attribute access. Comparing two
+    instances, placing instances in a set or dict, formatted-string conversion,
+    or stringifying a whole instance therefore reads fields the static scan
+    cannot otherwise observe, so the check is suppressed for the whole file.
+    """
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Compare):
+            return True
+        if isinstance(each_node, (ast.Set, ast.SetComp, ast.Dict, ast.DictComp)):
+            return True
+        if isinstance(each_node, ast.FormattedValue):
+            return True
+        if _is_whole_instance_stringify_call(each_node):
+            return True
+    return False
+
+
+def check_dead_dataclass_fields(
+    content: str, file_path: str, full_file_content: str | None = None
+) -> list[str]:
+    """Flag a @dataclass field that the same file constructs but never reads.
+
+    A field is dead when its dataclass is instantiated somewhere in the file
+    (so the class is live), the field name never appears as an attribute read,
+    an augmented-assignment target, a class-pattern keyword, or a literal
+    ``getattr``/``attrgetter`` access anywhere in the file, and the file contains
+    no non-literal dynamic access, reflective whole-instance consumer
+    (``asdict``, ``astuple``, ``fields``, ``replace``, ``vars``), ``__dict__``
+    read, or auto-generated dataclass dunder field read (comparison, set/dict
+    membership, or whole-instance stringification) that could read it
+    indirectly. Whole-file analysis runs against ``full_file_content`` when
+    supplied so an Edit fragment is judged against the reconstructed post-edit
+    file.
+
+    Args:
+        content: The new content under validation (Edit fragment or whole file).
+        file_path: The destination path, used for the test/registry exemptions.
+        full_file_content: The reconstructed post-edit whole-file content for an
+            Edit, or None for a Write where ``content`` is already the whole file.
+
+    Returns:
+        One violation message per dead dataclass field, capped at the configured
+        maximum.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_migration_file(file_path):
+        return []
+    effective_content = content if full_file_content is None else full_file_content
+    try:
+        tree = ast.parse(effective_content)
+    except SyntaxError:
+        return []
+    if _uses_dataclass_dunder_field_reads(tree):
+        return []
+    dynamic_literal_names, dynamic_access_suppresses_check = _dynamic_access_names(tree)
+    attribute_read_names, instance_dict_suppresses_check = _attribute_read_names(tree)
+    if dynamic_access_suppresses_check or instance_dict_suppresses_check:
+        return []
+    read_names = (
+        attribute_read_names
+        | dynamic_literal_names
+        | _match_pattern_attribute_names(tree)
+        | _exported_names(tree)
+    )
+    constructed_class_names = _constructed_class_names(tree)
+    issues: list[str] = []
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.ClassDef) or not _is_dataclass(each_node):
+            continue
+        if each_node.name not in constructed_class_names:
+            continue
+        for each_field_definition in _dataclass_field_definitions(each_node):
+            field_name, field_line = each_field_definition
+            if field_name in read_names:
+                continue
+            issues.append(
+                f"Line {field_line}: dataclass field {field_name!r} on {each_node.name}"
+                f" - {DEAD_DATACLASS_FIELD_GUIDANCE}"
+            )
+            if len(issues) >= MAX_DEAD_DATACLASS_FIELD_ISSUES:
+                return issues
+    return issues