claude-dev-env 1.82.0 → 1.84.0

package/hooks/blocking/code_rules_magic_values.py

@@ -17,6 +17,7 @@ from code_rules_path_utils import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     _extract_fstring_literal_parts,
+    docstring_line_numbers,
     is_test_file,
 )
 
@@ -156,6 +157,7 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
 
     issues = []
     lines = content.split("\n")
+    all_docstring_line_numbers = docstring_line_numbers(content)
     is_inside_function = False
 
     number_pattern = re.compile(r"(?<![.\w])(\d+\.?\d*)(?![.\w])")
@@ -167,6 +169,9 @@ def check_magic_values(content: str, file_path: str) -> list[str]:
         if not stripped:
             continue
 
+        if each_line_number in all_docstring_line_numbers:
+            continue
+
         if re.match(r"^(async\s+)?def\s+\w+", stripped):
             is_inside_function = True
             continue

package/hooks/blocking/code_rules_naming_collection.py

@@ -271,6 +271,147 @@ def check_loop_variable_naming(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _comprehension_rebinds_name(comprehension_node: ast.expr, target_name: str) -> bool:
+    """True when any generator of the comprehension binds its own target_name-named variable."""
+    generators = getattr(comprehension_node, "generators", [])
+    for each_generator in generators:
+        for each_name_node in _walk_assignment_targets(each_generator.target):
+            if each_name_node.id == target_name:
+                return True
+    return False
+
+
+def _function_binds_name(
+    function_node: ast.Lambda | ast.FunctionDef | ast.AsyncFunctionDef, target_name: str
+) -> bool:
+    """True when a lambda or nested def has a parameter named target_name."""
+    argument_specification = function_node.args
+    all_argument_nodes = [
+        *argument_specification.posonlyargs,
+        *argument_specification.args,
+        *argument_specification.kwonlyargs,
+    ]
+    if argument_specification.vararg is not None:
+        all_argument_nodes.append(argument_specification.vararg)
+    if argument_specification.kwarg is not None:
+        all_argument_nodes.append(argument_specification.kwarg)
+    return any(each_argument.arg == target_name for each_argument in all_argument_nodes)
+
+
+def _function_enclosing_scope_expressions(
+    function_node: ast.Lambda | ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[ast.expr]:
+    """Return the sub-expressions a lambda or def evaluates in its enclosing scope.
+
+    Parameter defaults and decorators run before the parameters bind, so a Load of
+    the outer name there still reads the outer name; the body never does once a
+    parameter shadows it.
+    """
+    argument_specification = function_node.args
+    enclosing_expressions: list[ast.expr] = [*argument_specification.defaults]
+    enclosing_expressions.extend(
+        each_default
+        for each_default in argument_specification.kw_defaults
+        if each_default is not None
+    )
+    if isinstance(function_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+        enclosing_expressions.extend(function_node.decorator_list)
+    return enclosing_expressions
+
+
+def _loop_rebinds_name(loop_node: ast.For | ast.AsyncFor, target_name: str) -> bool:
+    """True when the loop's own target rebinds target_name."""
+    return any(
+        each_name_node.id == target_name
+        for each_name_node in _walk_assignment_targets(loop_node.target)
+    )
+
+
+def _node_reads_name(node: ast.AST, target_name: str) -> bool:
+    """True when node contains a genuine Load of target_name, honoring scope shadowing.
+
+    A comprehension, a lambda, a nested def, or a nested loop that rebinds
+    target_name owns that name inside its body, so a Load there reads the inner
+    variable, not the outer loop variable. Only the parts each construct evaluates
+    in the enclosing scope can still read the outer name: a comprehension's or
+    nested loop's iterable, and a function's parameter defaults and decorators.
+    """
+    comprehension_node_types = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
+    if isinstance(node, comprehension_node_types) and _comprehension_rebinds_name(
+        node, target_name
+    ):
+        outermost_iterable = node.generators[0].iter
+        return _node_reads_name(outermost_iterable, target_name)
+    if isinstance(node, (ast.Lambda, ast.FunctionDef, ast.AsyncFunctionDef)) and _function_binds_name(
+        node, target_name
+    ):
+        return any(
+            _node_reads_name(each_expression, target_name)
+            for each_expression in _function_enclosing_scope_expressions(node)
+        )
+    if isinstance(node, (ast.For, ast.AsyncFor)) and _loop_rebinds_name(node, target_name):
+        return _node_reads_name(node.iter, target_name)
+    if isinstance(node, ast.Name) and node.id == target_name and isinstance(node.ctx, ast.Load):
+        return True
+    for each_child_node in ast.iter_child_nodes(node):
+        if _node_reads_name(each_child_node, target_name):
+            return True
+    return False
+
+
+def _loop_body_references_name(loop_node: ast.For | ast.AsyncFor, target_name: str) -> bool:
+    for each_statement in [*loop_node.body, *loop_node.orelse]:
+        if _node_reads_name(each_statement, target_name):
+            return True
+    return False
+
+
+def check_referenced_underscore_loop_variable(content: str, file_path: str) -> list[str]:
+    """Flag a leading-underscore loop variable the loop body reads.
+
+    A leading underscore marks a name as a throwaway the reader can ignore, so
+    ``for _foreign_module_name in names:`` promises the body never touches it.
+    When the body then reads ``del sys.modules[_foreign_module_name]``, the
+    marker lies: the value carries meaning and earns a real name. This check
+    fires in test files too — a conftest that reuses an underscore-marked loop
+    variable is the exact shape this closes — because the misleading marker is a
+    naming smell everywhere, not a convention the test-file exemption waives.
+    Workflow-registry and migration files are exempt. A bare ``_`` target and a
+    genuinely unread ``_unused`` throwaway both pass.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per leading-underscore loop variable that its loop body reads.
+    """
+    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.For, ast.AsyncFor)):
+            continue
+        for each_name_node in _collect_target_names(each_node.target):
+            target_name = each_name_node.id
+            if not target_name.startswith("_"):
+                continue
+            if target_name.strip("_") == "":
+                continue
+            if not _loop_body_references_name(each_node, target_name):
+                continue
+            issues.append(
+                f"Line {each_name_node.lineno}: loop variable {target_name!r} is read"
+                f" in its body - drop the leading underscore throwaway marker and"
+                f" give it a real name (CODE_RULES §5)"
+            )
+    return issues
+
+
 def _name_carries_token(name: str, token: str) -> bool:
     """True when name carries token as a whole underscore-delimited word."""
     return re.search(POLARITY_TOKEN_BOUNDARY_PATTERN % re.escape(token), name) is not None
@@ -295,12 +436,17 @@ def _contradicting_polarity_pair(target_name: str, called_name: str) -> tuple[st
 def check_polarity_name_contradiction(content: str, file_path: str) -> list[str]:
     """Flag a boolean assignment whose target and callee assert opposite polarity.
 
-    Catches the self-contradicting statement ``is_inside_allowed =
-    _point_hits_any_forbidden(...)`` — a target name carrying one polarity token
-    (``allowed``) assigned directly from a single call whose callee name carries
-    the antonym token (``forbidden``). One side lies about the behavior, so the
-    reader cannot trust either name. Rename the callee to a neutral form that
-    reads truthfully at every call site.
+    ::
+
+        is_inside_allowed = _point_hits_any_forbidden(...)
+                 ^^^^^^^                    ^^^^^^^^^
+                 allowed         vs.        forbidden      ⚠ the two names clash
+        ok:   is_inside_allowed = _point_inside_allowed_region(...)
+        flag: is_inside_allowed = _point_hits_any_forbidden(...)
+
+    The target token and the callee token contradict each other, so the reader
+    cannot tell which name states the truth. Rename the callee to a neutral form
+    the two names agree on at every call site.
     """
     if is_test_file(file_path):
         return []

package/hooks/blocking/code_rules_shared.py

@@ -273,6 +273,40 @@ def is_migration_file(file_path: str) -> bool:
     return any(pattern.replace("\\", "/") in path_lower for pattern in ALL_MIGRATION_PATH_PATTERNS)
 
 
+def docstring_line_numbers(content: str) -> set[int]:
+    """Return every source line that sits inside a string-literal statement.
+
+    A diagram-first docstring often draws its point across several lines, and
+    those lines can hold a bare number (a row marker) or a contrast row
+    (``flag: is_ok = do_thing(...)``). Those are prose, not code, so a
+    line-based lint check that reads them as literals fires a false positive.
+    This walks the parsed source and collects the line numbers spanned by every
+    string-literal expression statement — module, class, and function
+    docstrings, plus any bare string statement — so those checks can skip them.
+    Unparseable source yields an empty set.
+
+    Args:
+        content: The Python source to scan.
+
+    Returns:
+        The 1-indexed line numbers that fall inside a string-literal statement.
+    """
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return set()
+    all_docstring_line_numbers: set[int] = set()
+    for each_node in ast.walk(parsed_tree):
+        if not (isinstance(each_node, ast.Expr) and _statement_is_docstring(each_node)):
+            continue
+        end_line_number = each_node.end_lineno
+        if end_line_number is None:
+            continue
+        for each_line_number in range(each_node.lineno, end_line_number + 1):
+            all_docstring_line_numbers.add(each_line_number)
+    return all_docstring_line_numbers
+
+
 def _build_parent_map(module_tree: ast.Module) -> dict[int, ast.AST]:
     """Map child node id() to its parent node for ancestor walking."""
     parent_by_child_id: dict[int, ast.AST] = {}

package/hooks/blocking/code_rules_string_magic.py

@@ -123,6 +123,74 @@ def check_string_literal_magic(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def check_join_separator_string_magic(content: str, file_path: str) -> list[str]:
+    """Flag a bare string-literal separator passed to ``str.join`` in a body.
+
+    A call like ``", ".join(all_paths)`` hard-codes the delimiter that stitches
+    a list into one string. That delimiter is a magic value: change the wording
+    once and every reader has to grep the whole file for the stray literal. A
+    named constant in ``config/`` gives the delimiter one home. The empty
+    separator ``"".join(...)`` is left alone because it carries no delimiter —
+    it is the idiomatic way to concatenate parts. Config files, test files,
+    workflow-registry files, and migration files are exempt.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per non-empty string-literal ``.join`` separator found in a
+        function body.
+    """
+    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.Call):
+                    continue
+                separator_literal = _join_call_string_separator(each_descendant)
+                if separator_literal is None:
+                    continue
+                if id(each_descendant) in flagged_node_ids:
+                    continue
+                flagged_node_ids.add(id(each_descendant))
+                issues.append(
+                    f"Line {each_descendant.lineno}: string separator"
+                    f" {separator_literal!r} passed to .join(...)"
+                    f" - extract to a named constant in config/"
+                )
+    return issues
+
+
+def _join_call_string_separator(call_node: ast.Call) -> str | None:
+    called = call_node.func
+    if not isinstance(called, ast.Attribute):
+        return None
+    if called.attr != "join":
+        return None
+    separator_node = called.value
+    if not isinstance(separator_node, ast.Constant):
+        return None
+    if not isinstance(separator_node.value, str):
+        return None
+    if separator_node.value == "":
+        return None
+    return separator_node.value
+
+
 def check_inline_literal_collections(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []

package/hooks/blocking/duplicate_rmtree_helper_blocker.py

@@ -72,10 +72,10 @@ def path_is_exempt(file_path: str) -> bool:
     Returns:
         True when the path's basename is the canonical shared-helper home, an
         rmtree-blocker hook source, one of the existing in-repo definition sites
-        (session_env_cleanup.py, _md_to_html_blocker_test_support.py,
-        teardown_worktrees.py), or a test file. A definition there is intentional.
-        Basename equality (not substring containment) prevents a sibling whose name
-        merely contains an exempt fragment from bypassing the block.
+        (session_env_cleanup.py, teardown_worktrees.py), or a test file. A
+        definition there is intentional. Basename equality (not substring
+        containment) prevents a sibling whose name merely contains an exempt
+        fragment from bypassing the block.
     """
     normalized_path = file_path.replace("\\", "/")
     file_name = normalized_path.rsplit("/", 1)[-1]

package/hooks/blocking/pre_tool_use_dispatcher.py

@@ -8,9 +8,9 @@ decision when any hook denied (carrying every denying reason) or exits zero to
 allow.
 
 The per-hook coverage matrix:
-- Write  -> Group A (11 hooks) + Group B (7 hooks) = 18 hooks
-- Edit   -> Group A (11 hooks) + Group B (7 hooks) = 18 hooks
-- MultiEdit -> Group B only (7 hooks)
+- Write  -> Group A (11 hooks) + Group B (8 hooks) = 19 hooks
+- Edit   -> Group A (11 hooks) + Group B (8 hooks) + the Edit-only hook = 20 hooks
+- MultiEdit -> Group B only (8 hooks)
 """
 
 from __future__ import annotations

package/hooks/blocking/reviewer_spawn_gate.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block a reviewer-spawn trigger when that reviewer is down.
+
+autoconverge already skips a reviewer step when its own pre-check reports
+that reviewer unavailable. That skip only protects the trigger commands the
+workflow generates and inspects itself. This hook is the backstop: it reads
+the Bash command a tool call is about to run and blocks it when the matched
+reviewer reports unavailable.
+
+The gate only inspects a command carrying the literal sentinel marker
+`CLAUDE_REVIEWER_GATE=autoconverge`. autoconverge prepends this marker to its
+own trigger commands. A command without the marker is never inspected, so a
+manual or unrelated `gh` call always passes through untouched.
+
+A Copilot trigger is a command containing both `requested_reviewers` and
+`copilot-pull-request-reviewer[bot]`. A Bugbot trigger is a command
+containing `post_fix_reply.py` and a `--body "bugbot run"` argument.
+
+For the matched reviewer, the gate runs
+`reviewer_availability.py --reviewer copilot|bugbot` and denies the call only
+when that script exits with the documented reviewer-down code (3). Any other
+exit code is an unexpected script failure, not a down report, so the call is
+allowed (fail open). The deny reason names the reviewer and carries
+the script's output. The script path resolves relative to this hook's
+install location by default, or from the
+`REVIEWER_SPAWN_GATE_AVAILABILITY_SCRIPT_PATH` environment variable when set.
+A missing script, a timeout, or a failure to launch it allows the call
+(fail open), so a broken availability check never blocks a legitimate run.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.reviewer_spawn_gate_constants import (  # noqa: E402
+    ALL_COPILOT_TRIGGER_MARKERS,
+    AVAILABILITY_DOWN_EXIT_CODE,
+    AVAILABILITY_REVIEWER_FLAG,
+    AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME,
+    AVAILABILITY_SCRIPT_RELATIVE_PATH,
+    AVAILABILITY_SCRIPT_TIMEOUT_SECONDS,
+    BASH_TOOL_NAME,
+    BUGBOT_REVIEWER_LABEL,
+    BUGBOT_REVIEWER_TOKEN,
+    BUGBOT_RUN_BODY_PATTERN,
+    BUGBOT_TRIGGER_SCRIPT_MARKER,
+    COPILOT_REVIEWER_LABEL,
+    COPILOT_REVIEWER_TOKEN,
+    DENY_REASON_TEMPLATE,
+    GATE_SENTINEL_MARKER,
+)
+
+
+def _matches_copilot_trigger(command: str) -> bool:
+    return all(each_marker in command for each_marker in ALL_COPILOT_TRIGGER_MARKERS)
+
+
+def _matches_bugbot_trigger(command: str) -> bool:
+    return BUGBOT_TRIGGER_SCRIPT_MARKER in command and bool(
+        BUGBOT_RUN_BODY_PATTERN.search(command)
+    )
+
+
+def _reviewer_trigger(command: str) -> tuple[str, str] | None:
+    """Return the reviewer token and label a scoped command triggers.
+
+    Args:
+        command: The Bash command text carrying the gate's sentinel marker.
+
+    Returns:
+        The matched reviewer's CLI token paired with its display label, or
+        None when the command matches neither the Copilot review-request
+        shape nor the Bugbot rerun-comment shape.
+    """
+    if _matches_copilot_trigger(command):
+        return COPILOT_REVIEWER_TOKEN, COPILOT_REVIEWER_LABEL
+    if _matches_bugbot_trigger(command):
+        return BUGBOT_REVIEWER_TOKEN, BUGBOT_REVIEWER_LABEL
+    return None
+
+
+def _resolve_availability_script_path() -> Path:
+    override_path = os.environ.get(AVAILABILITY_SCRIPT_PATH_ENV_VAR_NAME, "")
+    if override_path:
+        return Path(override_path)
+    plugin_root = Path(__file__).resolve().parents[2]
+    return plugin_root / AVAILABILITY_SCRIPT_RELATIVE_PATH
+
+
+def _probe_reviewer_availability(reviewer_token: str) -> tuple[bool, str]:
+    """Run the shared availability script for a reviewer and report the outcome.
+
+    Args:
+        reviewer_token: The reviewer's CLI token (copilot or bugbot) passed to
+            the availability script's --reviewer flag.
+
+    Returns:
+        A pair of (is_available, detail_text). is_available is False only
+        when the script exits with the documented reviewer-down code;
+        detail_text carries the script's combined stdout and stderr for the
+        deny message. A missing script, a timeout, an OS-level failure to
+        launch the script, or any exit code other than the documented down
+        code reports available (fail open), so an availability-check crash
+        never blocks a legitimate run.
+    """
+    script_path = _resolve_availability_script_path()
+    if not script_path.is_file():
+        return True, f"availability script not found at {script_path}"
+    try:
+        completed_process = subprocess.run(
+            [sys.executable, str(script_path), AVAILABILITY_REVIEWER_FLAG, reviewer_token],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=AVAILABILITY_SCRIPT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.TimeoutExpired) as availability_error:
+        return True, f"availability script failed to run: {availability_error}"
+    availability_detail_text = (completed_process.stdout + completed_process.stderr).strip()
+    is_reviewer_down = completed_process.returncode == AVAILABILITY_DOWN_EXIT_CODE
+    return not is_reviewer_down, availability_detail_text
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+    if not isinstance(hook_input, dict):
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name != BASH_TOOL_NAME:
+        sys.exit(0)
+
+    tool_input = hook_input.get("tool_input", {})
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if not command or GATE_SENTINEL_MARKER not in command:
+        sys.exit(0)
+
+    reviewer_trigger = _reviewer_trigger(command)
+    if reviewer_trigger is None:
+        sys.exit(0)
+    reviewer_token, reviewer_label = reviewer_trigger
+
+    is_available, availability_detail = _probe_reviewer_availability(reviewer_token)
+    if is_available:
+        sys.exit(0)
+
+    deny_reason = DENY_REASON_TEMPLATE.format(
+        reviewer_label=reviewer_label, availability_detail=availability_detail
+    )
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+    log_hook_block(
+        calling_hook_name="reviewer_spawn_gate.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        tool_name=tool_name,
+        offending_input_preview=command,
+    )
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()