claude-dev-env 1.50.0 → 1.50.2

package/hooks/blocking/code_rules_imports_logging.py

@@ -0,0 +1,276 @@
+"""Imports-at-top, logging f-string, win32gui None, E2E spec naming, file-length advisory, and library-print 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
+    get_file_extension,
+    is_hook_infrastructure,
+    is_spec_file,
+    is_test_file,
+)
+
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    MAX_E2E_TEST_NAMING_ISSUES,
+    MAX_LOGGING_FSTRING_ISSUES,
+    MAX_WINDOWS_API_NONE_ISSUES,
+)
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ADVISORY_LINE_THRESHOLD_HARD,
+    ADVISORY_LINE_THRESHOLD_SOFT,
+    ALL_CLI_FILE_PATH_MARKERS,
+    ALL_IMPORT_STATEMENT_PREFIXES,
+    ALL_PYTHON_EXTENSIONS,
+    LOGGING_FSTRING_PATTERN,
+    NOT_INSIDE_TYPE_CHECKING_BLOCK,
+    TRIPLE_DOUBLE_QUOTE_DELIMITER,
+    TRIPLE_QUOTE_PARITY_DIVISOR,
+    TRIPLE_SINGLE_QUOTE_DELIMITER,
+    TYPE_CHECKING_BLOCK_PATTERN,
+)
+
+
+def check_imports_at_top(content: str) -> list[str]:
+    """Check for imports inside functions (Python only).
+
+    An import lexically inside an ``if TYPE_CHECKING:`` block is exempt.
+    An import inside a function body is flagged even if the file uses TYPE_CHECKING
+    elsewhere at module scope.
+
+    Only the innermost ``if TYPE_CHECKING:`` block is tracked: a second, nested
+    ``if TYPE_CHECKING:`` header overwrites the outer block's indent so that when
+    control dedents back to the outer block's body, the tracker resets.
+
+    Known limitation: nested ``if TYPE_CHECKING:`` blocks are NOT supported. After
+    a nested inner block ends, subsequent lines at the OUTER block's body indent
+    are treated as outside any TYPE_CHECKING scope, so function-body imports there
+    WILL be flagged as violations even though they are lexically guarded by the
+    outer block. Rewrite to a single top-level ``if TYPE_CHECKING:`` block to avoid
+    this false positive. Nested TYPE_CHECKING blocks are rare in practice, so this
+    simpler single-level tracking is preferred over maintaining a stack of indent
+    levels. The pinned behavior is covered by
+    ``test_should_track_only_innermost_type_checking_block``.
+
+    Triple-quoted-string interior lines are skipped. Once a line opens a
+    multi-line triple-double-quote or triple-single-quote string (odd count
+    of the delimiter), every subsequent line is treated as docstring content
+    and exempt from the import-prefix scan until the matching delimiter
+    closes the string. Without this tracking, docstring sentences that
+    happen to start with ``from `` or ``import `` after stripping (a common
+    pattern in narrative docstrings) would fire a false positive.
+    """
+    issues: list[str] = []
+    lines = content.split("\n")
+    is_inside_function = False
+    function_indent = 0
+    type_checking_block_indent = NOT_INSIDE_TYPE_CHECKING_BLOCK
+    active_triple_quote_delimiter: str | None = None
+
+    for each_line_number, each_line in enumerate(lines, 1):
+        if active_triple_quote_delimiter is not None:
+            active_triple_quote_delimiter = _update_triple_quote_state_for_line(
+                each_line, active_triple_quote_delimiter
+            )
+            continue
+
+        stripped = each_line.strip()
+
+        if not stripped:
+            continue
+
+        current_indent = len(each_line) - len(each_line.lstrip())
+
+        if type_checking_block_indent != NOT_INSIDE_TYPE_CHECKING_BLOCK:
+            if current_indent <= type_checking_block_indent:
+                type_checking_block_indent = NOT_INSIDE_TYPE_CHECKING_BLOCK
+
+        type_checking_match = TYPE_CHECKING_BLOCK_PATTERN.match(each_line)
+        if type_checking_match:
+            type_checking_block_indent = len(type_checking_match.group("indent"))
+            active_triple_quote_delimiter = _update_triple_quote_state_for_line(
+                each_line, active_triple_quote_delimiter
+            )
+            continue
+
+        function_match = re.match(r"^(\s*)(async\s+)?def\s+\w+", each_line)
+        if function_match:
+            is_inside_function = True
+            function_indent = len(function_match.group(1)) if function_match.group(1) else 0
+            active_triple_quote_delimiter = _update_triple_quote_state_for_line(
+                each_line, active_triple_quote_delimiter
+            )
+            continue
+
+        if is_inside_function:
+            if current_indent <= function_indent and stripped and not stripped.startswith(("#", "@", ")")):
+                is_inside_function = False
+
+        is_inside_type_checking_block = type_checking_block_indent != NOT_INSIDE_TYPE_CHECKING_BLOCK
+        if is_inside_function and not is_inside_type_checking_block:
+            if stripped.startswith(ALL_IMPORT_STATEMENT_PREFIXES):
+                issues.append(f"Line {each_line_number}: Import inside function - move to top of file")
+
+        active_triple_quote_delimiter = _update_triple_quote_state_for_line(
+            each_line, active_triple_quote_delimiter
+        )
+
+    return issues
+
+
+def _update_triple_quote_state_for_line(
+    line_text: str, current_delimiter: str | None
+) -> str | None:
+    """Return the triple-quote delimiter that remains active after the line.
+
+    Naively counts triple-double-quote and triple-single-quote occurrences.
+    An odd count of either delimiter toggles the active state: ``None``
+    becomes that delimiter, the same delimiter becomes ``None``. Even counts
+    mean the line opens and closes the same delimiter in place (single-line
+    docstring or balanced pair) and the active state is unchanged.
+
+    Known limitation: the counter does not distinguish triple quotes that
+    appear inside other string contexts (for example, a raw f-string
+    containing the literal substring of triple quotes). Such constructs are
+    rare in docstring-bearing code; the false-negative risk is acceptable
+    to keep the line-walker simple and dependency-free.
+
+    Args:
+        line_text: The raw source line whose triple-quote balance is being
+            integrated into the running state.
+        current_delimiter: The active delimiter at the start of this line,
+            or ``None`` when no multi-line string is open.
+
+    Returns:
+        The delimiter that remains active after this line, or ``None`` when
+        no string is open.
+    """
+    if current_delimiter is not None:
+        if line_text.count(current_delimiter) % TRIPLE_QUOTE_PARITY_DIVISOR == 1:
+            return None
+        return current_delimiter
+    if line_text.count(TRIPLE_DOUBLE_QUOTE_DELIMITER) % TRIPLE_QUOTE_PARITY_DIVISOR == 1:
+        return TRIPLE_DOUBLE_QUOTE_DELIMITER
+    if line_text.count(TRIPLE_SINGLE_QUOTE_DELIMITER) % TRIPLE_QUOTE_PARITY_DIVISOR == 1:
+        return TRIPLE_SINGLE_QUOTE_DELIMITER
+    return None
+
+
+def check_logging_fstrings(content: str) -> list[str]:
+    """Check for f-strings in logging calls."""
+    issues = []
+    pattern = LOGGING_FSTRING_PATTERN
+
+    maximum_issues = MAX_LOGGING_FSTRING_ISSUES
+    for each_line_number, each_line in enumerate(content.split("\n"), 1):
+        if pattern.search(each_line):
+            issues.append(f"Line {each_line_number}: f-string in log call - use format args instead")
+
+        if len(issues) >= maximum_issues:
+            break
+
+    return issues
+
+
+def advise_file_line_count(content: str, file_path: str) -> None:
+    """Emit non-blocking stderr advisories when a file crosses size smell thresholds.
+
+    Thresholds are smell signals, not hard caps. See CODE_RULES.md "File length guidance"
+    for rationale. Soft threshold aligns with Clean Code Chapter Five / Fowler "Large Class".
+    Hard threshold matches pylint default max-module-lines and SonarQube S104 default.
+    """
+    line_count = len(content.splitlines())
+    if line_count >= ADVISORY_LINE_THRESHOLD_HARD:
+        print(
+            f"[CODE_RULES advisory] {file_path}: {line_count} lines - "
+            f"exceeds pylint/SonarQube default ({ADVISORY_LINE_THRESHOLD_HARD}); "
+            f"strongly consider splitting by responsibility (SRP / cohesion)",
+            file=sys.stderr,
+        )
+    elif line_count >= ADVISORY_LINE_THRESHOLD_SOFT:
+        print(
+            f"[CODE_RULES advisory] {file_path}: {line_count} lines - "
+            f"consider splitting (Clean Code Ch. 5; Fowler 'Large Class' smell)",
+            file=sys.stderr,
+        )
+
+
+def check_windows_api_none(content: str) -> list[str]:
+    """Check for win32gui calls with None parameter."""
+    issues = []
+    pattern = re.compile(r"win32gui\.\w+\s*\([^)]*,\s*None\s*\)")
+
+    maximum_issues = MAX_WINDOWS_API_NONE_ISSUES
+    for each_line_number, each_line in enumerate(content.split("\n"), 1):
+        if pattern.search(each_line):
+            issues.append(f"Line {each_line_number}: win32gui call with None - use 0 for unused int params")
+
+        if len(issues) >= maximum_issues:
+            break
+
+    return issues
+
+
+def check_e2e_test_naming(content: str, file_path: str) -> list[str]:
+    """Check for online/offline in test names (spec files only)."""
+    if not is_spec_file(file_path):
+        return []
+
+    issues = []
+    pattern = re.compile(r'(test|it|describe)\s*\(\s*["\'][^"\']*\b(online|offline)\b[^"\']*["\']', re.IGNORECASE)
+
+    maximum_issues = MAX_E2E_TEST_NAMING_ISSUES
+    for each_line_number, each_line in enumerate(content.split("\n"), 1):
+        if pattern.search(each_line):
+            issues.append(f"Line {each_line_number}: Test name contains online/offline - file scope defines this")
+
+        if len(issues) >= maximum_issues:
+            break
+
+    return issues
+
+
+def _is_cli_entry_point(file_path: str) -> bool:
+    path_lower = file_path.lower().replace("\\", "/")
+    return any(marker.replace("\\", "/") in path_lower for marker in ALL_CLI_FILE_PATH_MARKERS)
+
+
+def check_library_print(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path) or is_config_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    if _is_cli_entry_point(file_path):
+        return []
+    if get_file_extension(file_path) not in ALL_PYTHON_EXTENSIONS:
+        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.Call):
+            continue
+        function_reference = each_node.func
+        if isinstance(function_reference, ast.Name) and function_reference.id == "print":
+            issues.append(
+                f"Line {each_node.lineno}: Library print() - route through logger or accept an explicit stream parameter"
+            )
+        elif isinstance(function_reference, ast.Attribute) and function_reference.attr == "write":
+            value_node = function_reference.value
+            if isinstance(value_node, ast.Attribute) and isinstance(value_node.value, ast.Name):
+                if value_node.value.id == "sys" and value_node.attr in {"stdout", "stderr"}:
+                    issues.append(
+                        f"Line {each_node.lineno}: sys.{value_node.attr}.write - route through logger"
+                    )
+    return issues

package/hooks/blocking/code_rules_magic_values.py

@@ -0,0 +1,180 @@
+"""Magic-number and f-string structural-literal checks for function bodies."""
+
+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
+    _extract_fstring_literal_parts,
+    is_test_file,
+)
+
+from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
+    ALL_ALLOWED_MAGIC_NUMBER_LITERALS,
+    ALL_NON_MAGIC_FSTRING_STRIPPED_VALUES,
+    MAX_FSTRING_STRUCTURAL_LITERAL_ISSUES,
+    MAX_MAGIC_VALUE_ISSUES,
+    MINIMUM_FSTRING_LITERAL_LENGTH,
+    STRING_LITERAL_QUOTE_PAIR_LENGTH,
+)
+
+
+def _mask_string_literals_preserving_length(source_line: str) -> str:
+    """Replace every string literal with an equal-length neutral placeholder.
+
+    Matching tests live in
+    ``test_code_rules_enforcer_magic_string_masking.py``, one of the
+    ``test_code_rules_enforcer_<suffix>.py`` family files the
+    ``tdd_enforcer.py`` hook accepts as test candidates for the
+    ``code_rules_*`` module family.
+    """
+
+    string_literal_pattern = re.compile(
+        r"(\"(?:\\.|[^\"\\])*\")|('(?:\\.|[^'\\])*')",
+    )
+
+    def _replace_string_literal(match: re.Match[str]) -> str:
+        matched_literal = match.group(0)
+        opening_quote = matched_literal[0]
+        closing_quote = matched_literal[-1]
+        inner_length = max(len(matched_literal) - STRING_LITERAL_QUOTE_PAIR_LENGTH, 0)
+        return f"{opening_quote}{'_' * inner_length}{closing_quote}"
+
+    return string_literal_pattern.sub(_replace_string_literal, source_line)
+
+
+def check_magic_values(content: str, file_path: str) -> list[str]:
+    """Check for magic values in function bodies."""
+    if is_config_file(file_path) or is_test_file(file_path):
+        return []
+
+    issues = []
+    lines = content.split("\n")
+    is_inside_function = False
+
+    number_pattern = re.compile(r"(?<![.\w])(\d+\.?\d*)(?![.\w])")
+    allowed_numbers = ALL_ALLOWED_MAGIC_NUMBER_LITERALS
+
+    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_function = False
+            continue
+
+        if is_inside_function:
+            if "=" in stripped and stripped.split("=")[0].strip().isupper():
+                continue
+
+            if stripped.startswith(("return", "yield", "raise")):
+                continue
+
+            stripped_without_string_literals = _mask_string_literals_preserving_length(stripped)
+            numbers_found = number_pattern.findall(stripped_without_string_literals)
+            for each_number in numbers_found:
+                if each_number not in allowed_numbers:
+                    if "range(" in stripped_without_string_literals or "enumerate(" in stripped_without_string_literals:
+                        continue
+                    if "[" in stripped_without_string_literals and "]" in stripped_without_string_literals:
+                        continue
+                    issues.append(f"Line {each_line_number}: Magic value {each_number} - extract to named constant")
+                    break
+
+        if len(issues) >= MAX_MAGIC_VALUE_ISSUES:
+            break
+
+    return issues
+
+
+def _has_structural_shape(literal_body: str) -> bool:
+    """Return True when a literal body looks like a path, URL, or regex.
+
+    Natural English containing a single slash (e.g. ``online/offline``,
+    ``CI/CD``, ``and/or``) must NOT match. Only multi-segment paths,
+    URL schemes, Windows drive prefixes, leading absolute paths, regex
+    escape sequences (``\\d``, ``\\w``, ``\\s`` and friends), or regex
+    anchors at the boundary are treated as structural.
+    """
+    if re.search(r"\w+/\w+/\w+", literal_body):
+        return True
+    if re.search(r"\w+\\\w+\\\w+", literal_body):
+        return True
+    if re.search(r"[A-Za-z][A-Za-z0-9+.\-]*://", literal_body):
+        return True
+    if re.search(r"(^|\s)[A-Za-z]:[\\/]", literal_body):
+        return True
+    if re.search(r"^/\w+/\w+", literal_body):
+        return True
+    if re.search(r"\\[dwsDWSbBAZ]|\\\d", literal_body):
+        return True
+    if literal_body.startswith("^") or literal_body.endswith("$"):
+        return True
+    return False
+
+
+def check_fstring_structural_literals(content: str, file_path: str) -> list[str]:
+    """Flag f-strings whose literal fragments look like paths, URLs, or regex.
+
+    Parses the file with :mod:`ast` so every f-string form is handled
+    uniformly: single, triple-quoted, raw (``rf`` / ``fr``), and strings
+    containing apostrophes or escaped braces. The literal portions of
+    each ``JoinedStr`` node are concatenated, and the result is treated
+    as a structural magic value only when :func:`_has_structural_shape`
+    matches a multi-segment path, a URL scheme, a Windows drive prefix,
+    a leading absolute path, a regex escape sequence, or a boundary
+    regex anchor.
+
+    The enforcer hook file, config files, and test files are all exempt.
+    Syntax errors in the input silently produce no issues, matching the
+    behaviour of the other lint-style checks in this module.
+    """
+    if is_config_file(file_path) or is_test_file(file_path):
+        return []
+    if file_path.replace("\\", "/").endswith("hooks/blocking/code_rules_enforcer.py"):
+        return []
+
+    try:
+        syntax_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    minimum_literal_length = MINIMUM_FSTRING_LITERAL_LENGTH
+    maximum_issues_before_stop = MAX_FSTRING_STRUCTURAL_LITERAL_ISSUES
+    non_magic_stripped_values = ALL_NON_MAGIC_FSTRING_STRIPPED_VALUES
+
+    issues: list[str] = []
+    for each_node in ast.walk(syntax_tree):
+        if not isinstance(each_node, ast.JoinedStr):
+            continue
+        display_body, shape_body = _extract_fstring_literal_parts(each_node)
+        if display_body in non_magic_stripped_values:
+            continue
+        if len(display_body) < minimum_literal_length:
+            continue
+        if not _has_structural_shape(shape_body):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: Structural literal inside f-string {display_body!r} - extract to config"
+        )
+        if len(issues) >= maximum_issues_before_stop:
+            break
+
+    return issues