claude-dev-env 1.50.1 → 1.50.3

package/hooks/blocking/code_rules_constants_config.py

@@ -0,0 +1,252 @@
+"""Constants-outside-config checks and the file-global constant use-count check."""
+
+import ast
+import re
+import sys
+from pathlib import Path
+from typing import Optional
+
+_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
+    _build_parent_map,
+    get_file_extension,
+    is_migration_file,
+    is_test_file,
+    is_workflow_registry_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_PYTHON_EXTENSIONS,
+    FILE_GLOBAL_UPPER_SNAKE_PATTERN,
+)
+
+
+def check_constants_outside_config(content: str, file_path: str) -> list[str]:
+    """Check for UPPER_SNAKE constants defined outside config files."""
+    if is_config_file(file_path):
+        return []
+
+    if is_test_file(file_path):
+        return []
+
+    if is_workflow_registry_file(file_path):
+        return []
+
+    if is_migration_file(file_path):
+        return []
+
+    issues = []
+    lines = content.split("\n")
+    is_inside_function = False
+    is_inside_class = False
+
+    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
+
+    for each_line_number, each_line in enumerate(lines, 1):
+        stripped = each_line.strip()
+
+        if not stripped:
+            continue
+
+        if re.match(r"^(async\s+)?def\s+\w+", stripped):
+            is_inside_function = True
+            continue
+
+        if re.match(r"^class\s+\w+", stripped):
+            is_inside_class = True
+            is_inside_function = False
+            continue
+
+        indent = len(each_line) - len(each_line.lstrip())
+        if indent == 0 and stripped and not stripped.startswith(("#", "@", ")")):
+            is_inside_function = False
+            is_inside_class = False
+
+        if not is_inside_function and not is_inside_class:
+            match = constant_pattern.match(stripped)
+            if match:
+                constant_name = match.group(1)
+                if constant_name not in ("__all__",):
+                    issues.append(f"Line {each_line_number}: Constant {constant_name} - move to config/")
+
+    return issues
+
+
+def _is_exempt_for_advisory_scan(file_path: str) -> bool:
+    """Return True when the file is exempt from the function-local UPPER_SNAKE advisory."""
+    if is_config_file(file_path):
+        return True
+    if is_test_file(file_path):
+        return True
+    if is_workflow_registry_file(file_path):
+        return True
+    if is_migration_file(file_path):
+        return True
+    return False
+
+
+def _scan_function_body_constants(content: str) -> list[str]:
+    """Return advisory messages for UPPER_SNAKE assignments inside function bodies.
+
+    Only lines inside a function body (tracked via an indent stack) are
+    flagged. Module-level assignments and class-body assignments are ignored.
+    """
+    advisory_issues: list[str] = []
+    lines = content.split("\n")
+    function_indent_stack: list[int] = []
+    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
+
+    for each_line_number, each_line in enumerate(lines, 1):
+        stripped = each_line.strip()
+
+        if not stripped:
+            continue
+
+        indent = len(each_line) - len(each_line.lstrip())
+
+        while function_indent_stack and indent <= function_indent_stack[-1] and not stripped.startswith(("#", "@", ")")):
+            function_indent_stack.pop()
+
+        if re.match(r"^class\s+\w+", stripped):
+            if indent == 0:
+                function_indent_stack.clear()
+            continue
+
+        if re.match(r"^(async\s+)?def\s+\w+", stripped):
+            function_indent_stack.append(indent)
+            continue
+
+        if function_indent_stack:
+            match = constant_pattern.match(stripped)
+            if match:
+                constant_name = match.group(1)
+                advisory_issues.append(
+                    f"Line {each_line_number}: Function-local constant {constant_name} - consider moving to config/"
+                )
+
+    return advisory_issues
+
+
+def check_constants_outside_config_advisory(content: str, file_path: str) -> list[str]:
+    """Return advisory entries for UPPER_SNAKE assignments inside function bodies.
+
+    Module-level UPPER_SNAKE outside config/ is blocking (see
+    check_constants_outside_config). Function-local UPPER_SNAKE is a softer
+    smell — it belongs in config/ but does not block the write. This function
+    surfaces those as advisory so callers can route them to stderr rather than
+    to the blocking deny payload.
+    """
+    if _is_exempt_for_advisory_scan(file_path):
+        return []
+    return _scan_function_body_constants(content)
+
+
+def _is_upper_snake_constant_name(name: str) -> bool:
+    """Return True for UPPER_SNAKE identifiers including those with a leading underscore."""
+    return bool(FILE_GLOBAL_UPPER_SNAKE_PATTERN.match(name))
+
+
+def _collect_module_level_upper_snake_constants(
+    module_tree: ast.Module,
+) -> dict[str, int]:
+    """Return mapping of module-level UPPER_SNAKE constant name to its line number."""
+    constants_by_name: dict[str, int] = {}
+    for each_node in module_tree.body:
+        if isinstance(each_node, ast.Assign):
+            for each_target in each_node.targets:
+                if isinstance(each_target, ast.Name) and _is_upper_snake_constant_name(each_target.id):
+                    constants_by_name.setdefault(each_target.id, each_node.lineno)
+        elif isinstance(each_node, ast.AnnAssign):
+            if isinstance(each_node.target, ast.Name) and _is_upper_snake_constant_name(each_node.target.id):
+                constants_by_name.setdefault(each_node.target.id, each_node.lineno)
+    return constants_by_name
+
+
+def _resolve_enclosing_function_qname(
+    load_node: ast.Name,
+    parent_by_child_id: dict[int, ast.AST],
+) -> Optional[str]:
+    """Return 'ClassName.function_name' or 'function_name' for the enclosing function.
+
+    Returns None when the reference is at module scope (no enclosing function).
+    Decorator expressions on a function/method count as belonging to that function.
+    """
+    enclosing_function_name: Optional[str] = None
+    enclosing_class_name: Optional[str] = None
+    current_ancestor = parent_by_child_id.get(id(load_node))
+    while current_ancestor is not None:
+        if isinstance(current_ancestor, (ast.FunctionDef, ast.AsyncFunctionDef)) and enclosing_function_name is None:
+            enclosing_function_name = current_ancestor.name
+        elif isinstance(current_ancestor, ast.ClassDef):
+            enclosing_class_name = current_ancestor.name
+            break
+        current_ancestor = parent_by_child_id.get(id(current_ancestor))
+    if enclosing_function_name is None:
+        if enclosing_class_name is not None:
+            return f"<class:{enclosing_class_name}>"
+        return None
+    if enclosing_class_name is not None:
+        return f"{enclosing_class_name}.{enclosing_function_name}"
+    return enclosing_function_name
+
+
+def check_file_global_constants_use_count(content: str, file_path: str) -> list[str]:
+    """Flag module-level UPPER_SNAKE constants referenced by only one function/method.
+
+    Enforces the file-global-constants use-count rule: a constant used by just
+    one caller belongs in that caller's scope. Test files, config files, and
+    non-Python files are exempt. Constants with zero references are out of
+    scope. The enforcer entry module (``hooks/blocking/code_rules_enforcer.py``)
+    is exempt to avoid self-blocking.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_config_file(file_path):
+        return []
+    if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
+        return []
+    if file_path.replace("\\", "/").endswith("hooks/blocking/code_rules_enforcer.py"):
+        return []
+
+    try:
+        module_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    constants_by_name = _collect_module_level_upper_snake_constants(module_tree)
+    if not constants_by_name:
+        return []
+
+    parent_by_child_id = _build_parent_map(module_tree)
+    callers_by_constant: dict[str, set[str]] = {name: set() for name in constants_by_name}
+    for each_node in ast.walk(module_tree):
+        if not isinstance(each_node, ast.Name):
+            continue
+        if not isinstance(each_node.ctx, ast.Load):
+            continue
+        if each_node.id not in callers_by_constant:
+            continue
+        enclosing_qname = _resolve_enclosing_function_qname(each_node, parent_by_child_id)
+        if enclosing_qname is None:
+            callers_by_constant[each_node.id].add("<module-scope>")
+        else:
+            callers_by_constant[each_node.id].add(enclosing_qname)
+
+    issues: list[str] = []
+    for each_constant_name, each_line_number in sorted(constants_by_name.items(), key=lambda pair: pair[1]):
+        caller_count = len(callers_by_constant[each_constant_name])
+        if caller_count == 1:
+            issues.append(
+                f"Line {each_line_number}: File-global constant {each_constant_name} used by only 1 function/method - move to method scope or add a second caller"
+            )
+
+    return issues

package/hooks/blocking/code_rules_docstrings.py

@@ -0,0 +1,308 @@
+"""Google-style docstring presence and docstring Args-versus-signature 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
+    _statement_is_docstring,
+    _walk_skipping_nested_functions,
+    _walk_skipping_type_checking_blocks,
+    is_hook_infrastructure,
+    is_test_file,
+)
+
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
+    ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES,
+    DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
+    MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
+    MAX_DOCSTRING_FORMAT_ISSUES,
+)
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_DOCSTRING_ARGS_SECTION_HEADERS,
+    ALL_DOCSTRING_TERMINATING_SECTION_HEADERS,
+    ALL_SELF_AND_CLS_PARAMETER_NAMES,
+    DOCSTRING_ARG_ENTRY_PATTERN,
+)
+
+
+def _function_is_private_or_dunder(function_name: str) -> bool:
+    if function_name.startswith("__") and function_name.endswith("__"):
+        return True
+    return function_name.startswith("_")
+
+
+def _decorator_label(decorator_node: ast.expr) -> str:
+    if isinstance(decorator_node, ast.Name):
+        return decorator_node.id
+    if isinstance(decorator_node, ast.Attribute):
+        prefix = (
+            decorator_node.value.id
+            if isinstance(decorator_node.value, ast.Name)
+            else ""
+        )
+        return f"{prefix}.{decorator_node.attr}" if prefix else decorator_node.attr
+    if isinstance(decorator_node, ast.Call):
+        return _decorator_label(decorator_node.func)
+    return ""
+
+
+def _function_has_exempt_decorator(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    for each_decorator in function_node.decorator_list:
+        if _decorator_label(each_decorator) in ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES:
+            return True
+    return False
+
+
+def _function_body_line_count(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> int:
+    if not function_node.body:
+        return 0
+    first_body_index = 0
+    if _statement_is_docstring(function_node.body[0]):
+        if len(function_node.body) == 1:
+            return 0
+        first_body_index = 1
+    last_statement = function_node.body[-1]
+    end_line = getattr(last_statement, "end_lineno", last_statement.lineno)
+    first_line = function_node.body[first_body_index].lineno
+    return max(0, end_line - first_line + 1)
+
+
+def _function_documentable_parameter_count(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> int:
+    documentable_count = 0
+    for each_argument in function_node.args.args:
+        if each_argument.arg in ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES:
+            continue
+        documentable_count += 1
+    documentable_count += len(function_node.args.kwonlyargs)
+    for each_argument in function_node.args.posonlyargs:
+        if each_argument.arg in ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES:
+            continue
+        documentable_count += 1
+    if function_node.args.vararg is not None:
+        documentable_count += 1
+    if function_node.args.kwarg is not None:
+        documentable_count += 1
+    return documentable_count
+
+
+def _annotation_is_explicit_none_return(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Constant) and annotation_node.value is None:
+        return True
+    return isinstance(annotation_node, ast.Name) and annotation_node.id == "None"
+
+
+def _annotation_is_noreturn(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Name) and annotation_node.id == "NoReturn":
+        return True
+    return isinstance(annotation_node, ast.Attribute) and annotation_node.attr == "NoReturn"
+
+
+def _function_body_contains_raise(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    return any(
+        isinstance(each_descendant, ast.Raise)
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+    )
+
+
+def _function_body_contains_yield(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    return any(
+        isinstance(each_descendant, (ast.Yield, ast.YieldFrom))
+        for each_descendant in _walk_skipping_nested_functions(function_node)
+    )
+
+
+def _function_docstring_text(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> str:
+    docstring_value = ast.get_docstring(function_node)
+    return docstring_value or ""
+
+
+def _missing_docstring_sections(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+    docstring_text = _function_docstring_text(function_node)
+    documentable_parameter_count = _function_documentable_parameter_count(function_node)
+    has_non_none_return = (
+        function_node.returns is not None
+        and not _annotation_is_explicit_none_return(function_node.returns)
+        and not _annotation_is_noreturn(function_node.returns)
+    )
+    has_raise_statement = _function_body_contains_raise(function_node)
+    has_yield_statement = _function_body_contains_yield(function_node)
+    missing_sections: list[str] = []
+    if documentable_parameter_count > 0 and "Args:" not in docstring_text:
+        missing_sections.append("Args:")
+    if has_non_none_return and not (
+        "Returns:" in docstring_text or "Yields:" in docstring_text
+    ):
+        section_label = "Yields:" if has_yield_statement else "Returns:"
+        missing_sections.append(section_label)
+    if has_raise_statement and "Raises:" not in docstring_text:
+        missing_sections.append("Raises:")
+    return missing_sections
+
+
+def check_docstring_format(content: str, file_path: str) -> list[str]:
+    """Flag public functions missing required Google-style docstring sections.
+
+    A public function whose signature has documentable parameters, returns
+    a non-None value, or raises must have the matching `Args:` / `Returns:`
+    (or `Yields:`) / `Raises:` sections so callers can read the contract
+    without scanning the body.
+    """
+    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_is_private_or_dunder(each_node.name):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        if _function_body_line_count(each_node) <= DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT:
+            continue
+        missing_sections = _missing_docstring_sections(each_node)
+        if not missing_sections:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring missing required "
+            f"section(s): {', '.join(missing_sections)} — Google style required for public APIs"
+        )
+        if len(issues) >= MAX_DOCSTRING_FORMAT_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_FORMAT_ISSUES]
+
+
+def _signature_parameter_names(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> set[str]:
+    arguments = function_node.args
+    real_names: set[str] = set()
+    for each_argument in arguments.posonlyargs + arguments.args + arguments.kwonlyargs:
+        real_names.add(each_argument.arg)
+    if arguments.vararg is not None:
+        real_names.add(arguments.vararg.arg)
+    if arguments.kwarg is not None:
+        real_names.add(arguments.kwarg.arg)
+    return real_names - ALL_SELF_AND_CLS_PARAMETER_NAMES
+
+
+def _is_docstring_terminating_section_header(stripped_line: str) -> bool:
+    return stripped_line in ALL_DOCSTRING_TERMINATING_SECTION_HEADERS
+
+
+def _documented_argument_names(docstring_text: str) -> list[str]:
+    docstring_lines = docstring_text.splitlines()
+    args_section_index = _find_args_section_index(docstring_lines)
+    if args_section_index is None:
+        return []
+    documented_names: list[str] = []
+    entry_indent: int | None = None
+    for each_line in docstring_lines[args_section_index + 1:]:
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        current_indent = len(each_line) - len(each_line.lstrip())
+        if current_indent == 0:
+            break
+        if entry_indent is None:
+            entry_indent = current_indent
+        if current_indent > entry_indent:
+            continue
+        entry_match = DOCSTRING_ARG_ENTRY_PATTERN.match(stripped_line)
+        if entry_match is not None:
+            documented_names.append(entry_match.group(1))
+    return documented_names
+
+
+def _find_args_section_index(all_docstring_lines: list[str]) -> int | None:
+    for each_line_index, each_line in enumerate(all_docstring_lines):
+        if each_line.strip() in ALL_DOCSTRING_ARGS_SECTION_HEADERS:
+            return each_line_index
+    return None
+
+
+def check_docstring_args_match_signature(content: str, file_path: str) -> list[str]:
+    """Flag docstring Args: entries naming a parameter the signature lacks.
+
+    A fix that renames a parameter often leaves the adjacent ``Args:`` line
+    stale. Each documented argument name is compared to the real signature;
+    a documented name with no matching parameter is reported. Only the
+    ``Args:`` section is validated — ``Raises:`` is left alone because
+    callee-propagated exceptions cause false positives. Functions that
+    accept ``**kwargs`` are skipped because their documented names may be
+    keyword keys the signature cannot enumerate.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per stale documented argument, 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_is_private_or_dunder(each_node.name):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        if _function_body_line_count(each_node) <= DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT:
+            continue
+        if each_node.args.kwarg is not None:
+            continue
+        documented_names = _documented_argument_names(_function_docstring_text(each_node))
+        if not documented_names:
+            continue
+        real_names = _signature_parameter_names(each_node)
+        for each_documented_name in documented_names:
+            if each_documented_name in real_names:
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}() docstring Args: lists "
+                f"'{each_documented_name}' which is not a parameter - update the "
+                "docstring to match the signature"
+            )
+            if len(issues) >= MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES:
+                return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+    return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]