claude-dev-env 1.50.0 → 1.50.2

package/hooks/blocking/code_rules_string_magic.py

@@ -0,0 +1,207 @@
+"""Bare string-literal magic, inline literal-collection, and inline tuple string-magic checks."""
+
+import ast
+import re
+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_path_utils import (  # noqa: E402
+    is_config_file,
+)
+from code_rules_shared import (  # noqa: E402
+    _walk_skipping_nested_function_defs,
+    is_migration_file,
+    is_test_file,
+    is_workflow_registry_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_CAPS_WITH_UNDERSCORE_PATTERN,
+    DOTTED_SEGMENT_PATTERN,
+    INLINE_COLLECTION_MIN_LENGTH,
+)
+from hooks_constants.inline_tuple_string_magic_constants import (  # noqa: E402
+    ALL_SNAKE_CASE_KEYWORD_EXEMPTIONS,
+    EXPECTED_TUPLE_PAIR_LENGTH,
+    INLINE_TUPLE_STRING_MAGIC_MESSAGE_SUFFIX,
+    MAX_INLINE_TUPLE_STRING_MAGIC_ISSUES,
+    SNAKE_CASE_LITERAL_PATTERN,
+)
+
+
+def _is_magic_string_literal(string_value: str) -> bool:
+    if not string_value:
+        return False
+    if ALL_CAPS_WITH_UNDERSCORE_PATTERN.match(string_value):
+        return True
+    if DOTTED_SEGMENT_PATTERN.match(string_value):
+        return True
+    return False
+
+
+def _collect_docstring_node_ids(tree: ast.Module) -> set[int]:
+    docstring_ids: set[int] = set()
+    docstring_owner_node_types = (
+        ast.Module,
+        ast.FunctionDef,
+        ast.AsyncFunctionDef,
+        ast.ClassDef,
+    )
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, docstring_owner_node_types):
+            continue
+        if not each_node.body:
+            continue
+        first_statement = each_node.body[0]
+        if not isinstance(first_statement, ast.Expr):
+            continue
+        first_value = first_statement.value
+        if isinstance(first_value, ast.Constant) and isinstance(first_value.value, str):
+            docstring_ids.add(id(first_value))
+    return docstring_ids
+
+
+def _collect_fstring_part_node_ids(tree: ast.Module) -> set[int]:
+    fstring_part_ids: set[int] = set()
+    for each_node in ast.walk(tree):
+        if not isinstance(each_node, ast.JoinedStr):
+            continue
+        for each_value in each_node.values:
+            if isinstance(each_value, ast.Constant) and isinstance(each_value.value, str):
+                fstring_part_ids.add(id(each_value))
+    return fstring_part_ids
+
+
+def check_string_literal_magic(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path):
+        return []
+    if is_config_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 []
+    docstring_node_ids = _collect_docstring_node_ids(tree)
+    fstring_part_node_ids = _collect_fstring_part_node_ids(tree)
+    issues: list[str] = []
+    flagged_node_ids: set[int] = set()
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in each_function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, ast.Constant):
+                    continue
+                if not isinstance(each_descendant.value, str):
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                if id(each_descendant) in docstring_node_ids:
+                    continue
+                if id(each_descendant) in fstring_part_node_ids:
+                    continue
+                if not _is_magic_string_literal(each_descendant.value):
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                issues.append(
+                    f"Line {each_descendant.lineno}: string magic value {each_descendant.value!r}"
+                    f" - extract to config/"
+                )
+    return issues
+
+
+def check_inline_literal_collections(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path):
+        return []
+    if is_config_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] = []
+    flagged_node_ids: set[int] = set()
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in each_function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, (ast.Set, ast.List)):
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                all_elements = each_descendant.elts
+                if len(all_elements) < INLINE_COLLECTION_MIN_LENGTH:
+                    continue
+                if not all(isinstance(each_element, ast.Constant) for each_element in all_elements):
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                collection_kind = "set" if isinstance(each_descendant, ast.Set) else "list"
+                issues.append(
+                    f"Line {each_descendant.lineno}: inline {collection_kind} literal of {len(all_elements)}"
+                    f" constants in function body - extract to config/"
+                )
+    return issues
+
+
+def check_inline_tuple_string_magic(content: str, file_path: str) -> list[str]:
+    """Flag inline two-tuple literals whose first element is a snake_case string.
+
+    Catches the pattern ``("kept", "Unknown status")`` and similar
+    column-name/key-value pairs declared inside function bodies. Files under
+    ``config/`` and test files are exempt because that is where named
+    constants are expected to live.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_config_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 []
+    snake_case_pattern = re.compile(SNAKE_CASE_LITERAL_PATTERN)
+    issues: list[str] = []
+    seen_tuple_node_ids: set[int] = set()
+    for each_function_node in ast.walk(tree):
+        if not isinstance(each_function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_body_statement in each_function_node.body:
+            for each_descendant in _walk_skipping_nested_function_defs(each_body_statement):
+                if not isinstance(each_descendant, ast.Tuple):
+                    continue
+                if id(each_descendant) in seen_tuple_node_ids:
+                    continue
+                seen_tuple_node_ids.add(id(each_descendant))
+                if len(each_descendant.elts) != EXPECTED_TUPLE_PAIR_LENGTH:
+                    continue
+                first_element = each_descendant.elts[0]
+                if not isinstance(first_element, ast.Constant):
+                    continue
+                if not isinstance(first_element.value, str):
+                    continue
+                literal_text = first_element.value
+                if not snake_case_pattern.match(literal_text):
+                    continue
+                if literal_text in ALL_SNAKE_CASE_KEYWORD_EXEMPTIONS:
+                    continue
+                issues.append(
+                    f"Line {first_element.lineno}: Column-name string magic "
+                    f"{literal_text!r} - {INLINE_TUPLE_STRING_MAGIC_MESSAGE_SUFFIX}"
+                )
+                if len(issues) >= MAX_INLINE_TUPLE_STRING_MAGIC_ISSUES:
+                    return issues
+    return issues

package/hooks/blocking/code_rules_test_assertions.py

@@ -0,0 +1,226 @@
+"""Skip-decorator, existence-only, and constant-equality test-quality checks."""
+
+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_test_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    UPPER_SNAKE_CONSTANT_PATTERN,
+)
+
+
+def _decorator_name_contains_skip(decorator_node: ast.expr) -> bool:
+    """Return True when a decorator AST node references an identifier containing 'skip'."""
+    if isinstance(decorator_node, ast.Name):
+        return "skip" in decorator_node.id.lower()
+    if isinstance(decorator_node, ast.Attribute):
+        return "skip" in decorator_node.attr.lower()
+    if isinstance(decorator_node, ast.Call):
+        return _decorator_name_contains_skip(decorator_node.func)
+    return False
+
+
+def check_skip_decorators_in_tests(content: str, file_path: str) -> list[str]:
+    """Flag @skip decorators on test functions in test files.
+
+    Tests must fail on missing dependencies rather than skip silently.
+    Only applies to test files; production files are exempt.
+    Only flags decorators applied to functions whose names start with 'test'.
+    """
+    if not is_test_file(file_path):
+        return []
+
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    issues: list[str] = []
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not each_node.name.startswith("test"):
+            continue
+        for each_decorator in each_node.decorator_list:
+            if _decorator_name_contains_skip(each_decorator):
+                issues.append(
+                    f"Line {each_decorator.lineno}: @skip decorator on test"
+                    f" — tests must fail on missing deps"
+                )
+
+    return issues
+
+
+def _collect_assert_nodes_bounded(node: ast.AST) -> list[ast.Assert]:
+    """Collect Assert nodes under node without crossing scope boundaries.
+
+    Terminates descent at FunctionDef, AsyncFunctionDef, ClassDef, and Lambda
+    nodes so that assertions belonging to nested scopes are not attributed to
+    the enclosing function body.
+    """
+    scope_boundary_types = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef, ast.Lambda)
+    assertions: list[ast.Assert] = []
+    nodes_to_visit: list[ast.AST] = list(ast.iter_child_nodes(node))
+    while nodes_to_visit:
+        current = nodes_to_visit.pop()
+        if isinstance(current, ast.Assert):
+            assertions.append(current)
+        if isinstance(current, scope_boundary_types):
+            continue
+        nodes_to_visit.extend(ast.iter_child_nodes(current))
+    return assertions
+
+
+def _collect_body_assertions(statement_nodes: list[ast.stmt]) -> list[ast.Assert]:
+    """Collect Assert nodes from a function body without descending into nested scopes."""
+    assertions: list[ast.Assert] = []
+    for each_stmt in statement_nodes:
+        if isinstance(each_stmt, ast.Assert):
+            assertions.append(each_stmt)
+            continue
+        if isinstance(each_stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        assertions.extend(_collect_assert_nodes_bounded(each_stmt))
+    return assertions
+
+
+def _is_existence_only_assertion(call_node: ast.Call) -> bool:
+    """Return True when a Call node is callable() or hasattr()."""
+    function_reference = call_node.func
+    if isinstance(function_reference, ast.Name):
+        return function_reference.id in ("callable", "hasattr")
+    if isinstance(function_reference, ast.Attribute):
+        return function_reference.attr in ("callable", "hasattr")
+    return False
+
+
+def _test_body_has_only_existence_assertions(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when a test function body contains only existence-check assertions."""
+    assertion_nodes = _collect_body_assertions(function_node.body)
+    if not assertion_nodes:
+        return False
+
+    non_existence_assertions = 0
+    for each_assert in assertion_nodes:
+        test_expr = each_assert.test
+        if isinstance(test_expr, ast.Call) and _is_existence_only_assertion(test_expr):
+            continue
+        if isinstance(test_expr, ast.Compare):
+            comparators = test_expr.comparators
+            ops = test_expr.ops
+            if (
+                len(ops) == 1
+                and isinstance(ops[0], ast.IsNot)
+                and len(comparators) == 1
+                and isinstance(comparators[0], ast.Constant)
+                and comparators[0].value is None
+            ):
+                continue
+        non_existence_assertions += 1
+
+    return non_existence_assertions == 0
+
+
+def check_existence_check_tests(content: str, file_path: str) -> list[str]:
+    """Flag test functions containing only existence-check assertions.
+
+    Tests asserting only callable(x), hasattr(m, 'name'), or x is not None
+    verify nothing about behavior. They should be deleted or replaced with
+    assertions that exercise actual functionality.
+    Only applies to test files.
+    """
+    if not is_test_file(file_path):
+        return []
+
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    issues: list[str] = []
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not each_node.name.startswith("test"):
+            continue
+        if _test_body_has_only_existence_assertions(each_node):
+            issues.append(
+                f"Line {each_node.lineno}: existence-check test"
+                f" — delete or replace with a behavior test"
+            )
+
+    return issues
+
+
+def _is_upper_snake_name(name: str) -> bool:
+    """Return True when an identifier is written in UPPER_SNAKE_CASE."""
+    return bool(UPPER_SNAKE_CONSTANT_PATTERN.match(name))
+
+
+def _assert_is_constant_equality_only(assert_node: ast.Assert) -> bool:
+    """Return True when the assertion compares an UPPER_SNAKE name to a literal."""
+    test_expr = assert_node.test
+    if not isinstance(test_expr, ast.Compare):
+        return False
+    if len(test_expr.ops) != 1 or not isinstance(test_expr.ops[0], ast.Eq):
+        return False
+    left = test_expr.left
+    right = test_expr.comparators[0]
+    is_left_upper_snake = isinstance(left, ast.Name) and _is_upper_snake_name(left.id)
+    is_right_upper_snake = isinstance(right, ast.Name) and _is_upper_snake_name(right.id)
+    if is_left_upper_snake and is_right_upper_snake:
+        return False
+    is_left_a_literal = isinstance(left, ast.Constant)
+    is_right_a_literal = isinstance(right, ast.Constant)
+    return (
+        (is_left_upper_snake and is_right_a_literal)
+        or (is_right_upper_snake and is_left_a_literal)
+    )
+
+
+def check_constant_equality_tests(content: str, file_path: str) -> list[str]:
+    """Flag test functions whose sole assertion compares a constant to a literal.
+
+    Tests like 'assert CACHE_DIR == "cache"' cover no behavior — they just
+    verify the constant has not changed. Such tests should be deleted.
+    Only applies to test files; production files are exempt.
+    """
+    if not is_test_file(file_path):
+        return []
+
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    issues: list[str] = []
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if not each_node.name.startswith("test"):
+            continue
+        all_assertions = _collect_body_assertions(each_node.body)
+        if not all_assertions:
+            continue
+        if len(all_assertions) > 1:
+            continue
+        if _assert_is_constant_equality_only(all_assertions[0]):
+            issues.append(
+                f"Line {each_node.lineno}: constant-value test"
+                f" — delete; tests must cover behavior"
+            )
+
+    return issues

package/hooks/blocking/code_rules_test_branching_except.py

@@ -0,0 +1,181 @@
+"""Test-mode branching in production and bare-except checks."""
+
+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
+    _walk_skipping_type_checking_blocks,
+    is_hook_infrastructure,
+    is_test_file,
+)
+
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES,
+    ALL_TEST_INDICATING_ENVIRONMENT_VARIABLE_NAMES,
+    MAX_BARE_EXCEPT_ISSUES,
+    MAX_TEST_BRANCHING_ISSUES,
+)
+
+
+def _string_constant_value(node: ast.expr) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _is_environ_attribute(node: ast.expr) -> bool:
+    if isinstance(node, ast.Attribute) and node.attr == "environ":
+        return isinstance(node.value, ast.Name) and node.value.id == "os"
+    return False
+
+
+def _environ_get_call_argument_names(call_node: ast.Call) -> list[str]:
+    function_node = call_node.func
+    if not isinstance(function_node, ast.Attribute):
+        return []
+    if function_node.attr != "get":
+        return []
+    if not _is_environ_attribute(function_node.value):
+        return []
+    if not call_node.args:
+        return []
+    first_argument = _string_constant_value(call_node.args[0])
+    return [first_argument] if first_argument is not None else []
+
+
+def _environ_subscript_key_names(subscript_node: ast.Subscript) -> list[str]:
+    if not _is_environ_attribute(subscript_node.value):
+        return []
+    key = _string_constant_value(subscript_node.slice)
+    return [key] if key is not None else []
+
+
+def _environ_membership_key_names(compare_node: ast.Compare) -> list[str]:
+    if not compare_node.ops:
+        return []
+    if not isinstance(compare_node.ops[0], (ast.In, ast.NotIn)):
+        return []
+    if not compare_node.comparators:
+        return []
+    if not _is_environ_attribute(compare_node.comparators[0]):
+        return []
+    key = _string_constant_value(compare_node.left)
+    return [key] if key is not None else []
+
+
+def _collect_test_env_variable_references(parsed_tree: ast.AST) -> list[tuple[int, str]]:
+    references: list[tuple[int, str]] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        candidate_names: list[str] = []
+        if isinstance(each_node, ast.Call):
+            candidate_names = _environ_get_call_argument_names(each_node)
+        elif isinstance(each_node, ast.Subscript):
+            candidate_names = _environ_subscript_key_names(each_node)
+        elif isinstance(each_node, ast.Compare):
+            candidate_names = _environ_membership_key_names(each_node)
+        for each_candidate_name in candidate_names:
+            if each_candidate_name in ALL_TEST_INDICATING_ENVIRONMENT_VARIABLE_NAMES:
+                references.append((each_node.lineno, each_candidate_name))
+    return references
+
+
+def check_test_branching_in_production(content: str, file_path: str) -> list[str]:
+    """Flag production code that branches on TESTING-style env vars.
+
+    Production code reading TESTING / PYTEST_CURRENT_TEST creates two
+    parallel implementations and hides bugs. Use dependency injection
+    (override the dependency in tests) instead.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    references = _collect_test_env_variable_references(parsed_tree)
+    references.sort(key=lambda each_reference: each_reference[0])
+
+    issues: list[str] = []
+    already_reported_lines: set[int] = set()
+    for each_line_number, each_variable_name in references:
+        if each_line_number in already_reported_lines:
+            continue
+        already_reported_lines.add(each_line_number)
+        issues.append(
+            f"Line {each_line_number}: Production code reads test indicator '{each_variable_name}' — "
+            "use dependency injection so production stays single-path"
+        )
+        if len(issues) >= MAX_TEST_BRANCHING_ISSUES:
+            break
+
+    return issues
+
+
+def _bare_except_handler_label(handler_node: ast.ExceptHandler) -> str | None:
+    """Return a label for handlers we flag, or None for safe handlers."""
+    handler_type = handler_node.type
+    if handler_type is None:
+        return "bare except:"
+    if isinstance(handler_type, ast.Name) and handler_type.id in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES:
+        return f"except {handler_type.id}:"
+    if (
+        isinstance(handler_type, ast.Attribute)
+        and handler_type.attr in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES
+    ):
+        return f"except {handler_type.attr}:"
+    if isinstance(handler_type, ast.Tuple):
+        banned_names: list[str] = []
+        for each_element in handler_type.elts:
+            if isinstance(each_element, ast.Name) and each_element.id in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES:
+                banned_names.append(each_element.id)
+            elif (
+                isinstance(each_element, ast.Attribute)
+                and each_element.attr in ALL_BARE_EXCEPT_BANNED_HANDLER_NAMES
+            ):
+                banned_names.append(each_element.attr)
+        if banned_names:
+            return f"except {', '.join(banned_names)} (in tuple):"
+    return None
+
+
+def check_bare_except(content: str, file_path: str) -> list[str]:
+    """Flag bare/over-broad exception handlers in production code.
+
+    ``except:`` and ``except BaseException:`` swallow KeyboardInterrupt and
+    SystemExit; ``except Exception:`` hides bugs by catching nearly every
+    error class. Production code should name the specific exception(s) it
+    intends to catch
+    (a tuple form like `except (ValueError, KeyError):` is fine).
+    """
+    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.ExceptHandler):
+            continue
+        handler_label = _bare_except_handler_label(each_node)
+        if handler_label is None:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {handler_label} is over-broad — name the "
+            "specific exception(s) you intend to handle"
+        )
+        if len(issues) >= MAX_BARE_EXCEPT_ISSUES:
+            break
+    return issues