claude-dev-env 1.92.1 → 1.93.0

package/hooks/blocking/code_rules_test_layout.py

@@ -0,0 +1,272 @@
+"""Test-module dead-scaffolding checks: dead constant, unused helper parameter.
+
+Both checks run on a test module where scaffolding left after an edit hides in
+plain sight: when a removed monkeypatch line was the last reader of a module
+constant, or the last user of a private helper's parameter, the leftover is
+dead code the checks flag at Write/Edit time.
+
+The dead-constant check runs only on a ``test_*.py`` / ``*_test.py`` module of
+test functions, which exports nothing, so a single-file scan proves a constant
+no other line reads is dead. A ``conftest.py``, a shared helper module reached
+only through the ``tests/`` directory gate, and a dedicated constants or
+``config/`` module all export their constants to importer modules, so the
+cross-module ``check_dead_module_constants`` governs their constants and the
+dead-constant check leaves them alone.
+"""
+
+import ast
+from typing import TypeGuard
+
+from code_rules_dead_module_constant import _is_dedicated_constants_module
+from code_rules_shared import is_strict_test_file
+from hooks_constants.test_layout_constants import (
+    CLASS_METHOD_FIRST_PARAMETER_NAME,
+    DEAD_TEST_CONSTANT_GUIDANCE,
+    FIXTURE_DECORATOR_MARKER,
+    MAX_TEST_LAYOUT_ISSUES,
+    MINIMUM_CONSTANT_NAME_LENGTH,
+    PRIVATE_NAME_PREFIX,
+    SELF_PARAMETER_NAME,
+    TEST_FUNCTION_MODULE_BASENAME_PATTERN,
+    UNUSED_TEST_HELPER_PARAMETER_GUIDANCE,
+)
+
+_FunctionNode = ast.FunctionDef | ast.AsyncFunctionDef
+
+
+def _parse_module(content: str) -> ast.Module | None:
+    """Return the parsed module, or None when the content does not parse."""
+    try:
+        return ast.parse(content)
+    except SyntaxError:
+        return None
+
+def _is_dead_constant_scan_target(file_path: str) -> bool:
+    """Return whether a single-file dead-constant scan can judge this module.
+
+    ::
+
+        tests/test_report.py                      -> scan  (test functions export nothing)
+        tests/conftest.py                         -> skip  (fixtures shared with siblings)
+        tests/expected_values.py                  -> skip  (a shared module exports)
+        hooks_constants/test_layout_constants.py  -> skip  (a constants module exports)
+
+    A ``test_*`` / ``*_test`` module of test functions exports nothing, so a
+    constant no other line reads is dead. A ``conftest.py``, a shared helper
+    module reached only through the ``tests/`` directory gate, and a dedicated
+    constants or ``config/`` module all export to importer modules, where the
+    cross-module ``check_dead_module_constants`` governs their constants.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True only for a ``test_*.py`` / ``*_test.py`` module that is not a
+        dedicated constants or ``config/`` module.
+    """
+    if _is_dedicated_constants_module(file_path):
+        return False
+    basename = file_path.lower().replace("\\", "/").rsplit("/", 1)[-1]
+    return TEST_FUNCTION_MODULE_BASENAME_PATTERN.match(basename) is not None
+
+def _is_private_constant_name(name: str) -> bool:
+    """Return whether a name is a private UPPER_SNAKE constant identifier.
+
+    ::
+
+        _ABSENT_DOTENV_FILENAME  ->  private constant, judged
+        EXPECTED_TOTAL           ->  public constant, left alone
+
+    Only a leading-underscore name qualifies. A public module constant exports
+    to importer modules, so the cross-module ``check_dead_module_constants``
+    governs it and this single-file scan leaves it alone.
+    """
+    if not name.startswith(PRIVATE_NAME_PREFIX):
+        return False
+    if len(name) < MINIMUM_CONSTANT_NAME_LENGTH:
+        return False
+    if not name.replace("_", "").isalnum():
+        return False
+    return name == name.upper() and any(each_char.isalpha() for each_char in name)
+
+def _assignment_targets(statement: ast.stmt) -> list[ast.expr]:
+    """Return the assignment targets of a plain or annotated assignment."""
+    if isinstance(statement, ast.Assign):
+        return list(statement.targets)
+    if isinstance(statement, ast.AnnAssign) and statement.value is not None:
+        return [statement.target]
+    return []
+
+def _statement_constant_targets(statement: ast.stmt) -> list[tuple[str, int]]:
+    """Return (name, line) for each private UPPER_SNAKE constant one statement binds."""
+    named_targets: list[tuple[str, int]] = []
+    for each_target in _assignment_targets(statement):
+        if isinstance(each_target, ast.Name) and _is_private_constant_name(each_target.id):
+            named_targets.append((each_target.id, statement.lineno))
+    return named_targets
+
+def _module_constant_targets(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return (name, line) for every module-scope private UPPER_SNAKE constant, in order."""
+    constant_targets: list[tuple[str, int]] = []
+    for each_statement in tree.body:
+        constant_targets.extend(_statement_constant_targets(each_statement))
+    return constant_targets
+
+def _referenced_names(tree: ast.Module) -> set[str]:
+    """Return every name the module reads plus every string literal it holds.
+
+    A ``Load``-context name is a read; a ``Store`` target (the constant's own
+    definition) is not, so a constant read nowhere else stays out of the set.
+    String literals are unioned in so an ``__all__`` or ``getattr`` string name
+    still counts.
+    """
+    all_nodes = list(ast.walk(tree))
+    load_names = {
+        each_node.id
+        for each_node in all_nodes
+        if isinstance(each_node, ast.Name) and isinstance(each_node.ctx, ast.Load)
+    }
+    literal_values = {
+        each_node.value
+        for each_node in all_nodes
+        if isinstance(each_node, ast.Constant) and isinstance(each_node.value, str)
+    }
+    return load_names | literal_values
+
+def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> list[str]:
+    """Return one message per module constant absent from the referenced set."""
+    issues: list[str] = []
+    for each_name, each_line in _module_constant_targets(tree):
+        if each_name in referenced_names:
+            continue
+        issues.append(
+            f"Line {each_line}: constant {each_name!r} - {DEAD_TEST_CONSTANT_GUIDANCE}"
+        )
+        if len(issues) >= MAX_TEST_LAYOUT_ISSUES:
+            break
+    return issues
+
+def check_dead_test_module_constant(content: str, file_path: str) -> list[str]:
+    """Flag a private module-level constant in a test-function module no line reads.
+
+    ::
+
+        tests/test_report.py, a private UPPER_SNAKE constant no Load reference
+        and no string literal names   ->   dead scaffolding, flag it
+        tests/test_report.py, a public constant (EXPECTED_TOTAL)   ->   skip
+        tests/conftest.py / tests/expected_values.py / *_constants.py   ->   skip
+
+    A private constant read by no reference and named in no string literal is
+    dead scaffolding an edit stranded. A public constant, a ``conftest.py``, a
+    shared helper module under ``tests/``, and a dedicated constants or
+    ``config/`` module all export to importer modules, so the cross-module
+    ``check_dead_module_constants`` judges those and this check skips them.
+
+    Args:
+        content: The post-edit file content under validation.
+        file_path: The destination path, used for the test-function-module gate.
+
+    Returns:
+        One message per dead private constant, capped at the configured maximum.
+    """
+    if not _is_dead_constant_scan_target(file_path):
+        return []
+    tree = _parse_module(content)
+    if tree is None:
+        return []
+    return _dead_constant_messages(tree, _referenced_names(tree))
+
+def _node_names_fixture(node: ast.AST) -> bool:
+    """Return whether one decorator sub-node spells the pytest fixture marker."""
+    if isinstance(node, ast.Name):
+        return FIXTURE_DECORATOR_MARKER in node.id
+    if isinstance(node, ast.Attribute):
+        return FIXTURE_DECORATOR_MARKER in node.attr
+    return False
+
+def _has_fixture_decorator(function_node: _FunctionNode) -> bool:
+    """Return whether a function carries a pytest fixture decorator.
+
+    A fixture parameter is injected by pytest and read by name only, so a
+    fixture must never be judged for unused parameters.
+    """
+    for each_decorator in function_node.decorator_list:
+        if any(
+            _node_names_fixture(each_node) for each_node in ast.walk(each_decorator)
+        ):
+            return True
+    return False
+
+def _is_judged_parameter(parameter_name: str) -> bool:
+    """Return whether a parameter name is worth judging for being unread.
+
+    ``self`` and ``cls`` are receiver names, and an underscore-prefixed name is
+    a conventional throwaway, so none of the three are judged.
+    """
+    if parameter_name in {SELF_PARAMETER_NAME, CLASS_METHOD_FIRST_PARAMETER_NAME}:
+        return False
+    return not parameter_name.startswith(PRIVATE_NAME_PREFIX)
+
+def _candidate_parameters(function_node: _FunctionNode) -> list[ast.arg]:
+    """Return the parameters of a function worth judging for being unread."""
+    arguments = function_node.args
+    all_parameters = arguments.posonlyargs + arguments.args + arguments.kwonlyargs
+    return [each for each in all_parameters if _is_judged_parameter(each.arg)]
+
+def _read_parameter_names(function_node: _FunctionNode) -> set[str]:
+    """Return every name read anywhere in a function body."""
+    return {
+        each_node.id
+        for each_node in ast.walk(function_node)
+        if isinstance(each_node, ast.Name) and isinstance(each_node.ctx, ast.Load)
+    }
+
+def _unused_parameter_messages(function_node: _FunctionNode) -> list[str]:
+    """Return one message per candidate parameter the function body never reads."""
+    read_names = _read_parameter_names(function_node)
+    issues: list[str] = []
+    for each_parameter in _candidate_parameters(function_node):
+        if each_parameter.arg in read_names:
+            continue
+        issues.append(
+            f"Line {each_parameter.lineno}: parameter {each_parameter.arg!r}"
+            f" on {function_node.name!r} - {UNUSED_TEST_HELPER_PARAMETER_GUIDANCE}"
+        )
+    return issues
+
+def _is_private_plain_function(statement: ast.stmt) -> TypeGuard[_FunctionNode]:
+    """Return whether a statement is a private, non-fixture module-level function."""
+    if not isinstance(statement, ast.FunctionDef | ast.AsyncFunctionDef):
+        return False
+    if not statement.name.startswith(PRIVATE_NAME_PREFIX):
+        return False
+    return not _has_fixture_decorator(statement)
+
+def check_unused_test_helper_parameter(content: str, file_path: str) -> list[str]:
+    """Flag a parameter of a private test helper that its body never reads.
+
+    ::
+
+        def _configuration(monkeypatch, tmp_path):   neither read -> flag
+            return DatabaseConfig.from_environment()
+
+    A private module-level function carries no pytest fixture decorator, so its
+    parameter is never injected by name, and one the body never reads is dead.
+
+    Args:
+        content: The post-edit file content under validation.
+        file_path: The destination path, used for the test-file gate.
+
+    Returns:
+        One message per unused private-helper parameter, capped at the maximum.
+    """
+    if not is_strict_test_file(file_path):
+        return []
+    tree = _parse_module(content)
+    if tree is None:
+        return []
+    issues: list[str] = []
+    for each_statement in tree.body:
+        if _is_private_plain_function(each_statement):
+            issues.extend(_unused_parameter_messages(each_statement))
+    return issues[:MAX_TEST_LAYOUT_ISSUES]

package/hooks/blocking/nas_ssh_binary_enforcer.py

@@ -15,7 +15,7 @@ found by skipping ``VAR=value`` assignments and launcher wrappers (``timeout``,
 ``nohup``, ``nice``, ``stdbuf``, ``setsid``, ``env``) with their flags and duration
 arguments. A segment is evaluated only when its leading program's basename is
 ``ssh``/``scp``/``sftp`` (with or without a ``.exe`` suffix) AND a token in that same
-segment holds the NAS address ``192.168.1.100`` as a connection host — bare,
+segment holds the NAS host (resolved from the ``CLAUDE_NAS_*`` environment variables or ``~/.claude/local-identity.json``) as a connection host — bare,
 ``user@host``, or a ``host:path`` target. The address inside a remote-command
 argument or a remote path component on another host does not count.
 
@@ -30,6 +30,7 @@ without an ssh-family leading program, and a command shlex cannot tokenize.
 """
 
 import json
+import re
 import shlex
 import sys
 from pathlib import Path
@@ -39,19 +40,21 @@ 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.local_identity import (  # noqa: E402
+    bare_ssh_binary_deny_message,
+    missing_batch_mode_deny_message,
+    nas_host,
+)
 from hooks_constants.nas_ssh_binary_enforcer_constants import (  # noqa: E402
     ALL_LAUNCHER_WRAPPER_COMMANDS,
     ALL_OPENSSH_BINARY_PATH_SUFFIXES,
     ALL_SHELL_CONTROL_OPERATOR_TOKENS,
     ALL_SSH_FAMILY_COMMAND_BASENAMES,
-    BARE_SSH_BINARY_MESSAGE,
     BASH_TOOL_NAME,
     BATCH_MODE_PATTERN,
     CONTROL_OPERATOR_SPLIT_PATTERN,
     LAUNCHER_DURATION_PATTERN,
     LEADING_ASSIGNMENT_PATTERN,
-    MISSING_BATCH_MODE_MESSAGE,
-    NAS_HOST_TOKEN_PATTERN,
 )
 
 
@@ -67,6 +70,10 @@ def _is_openssh_binary_path(token: str) -> bool:
     )
 
 
+def _nas_host_token_pattern() -> re.Pattern[str]:
+    return re.compile(rf"(?:^|@){re.escape(nas_host())}(?::|$)")
+
+
 def _split_into_segments(all_command_tokens: list[str]) -> list[list[str]]:
     all_exploded_tokens: list[str] = []
     for each_token in all_command_tokens:
@@ -101,8 +108,10 @@ def _effective_leading_program(all_segment_tokens: list[str]) -> str | None:
     return None
 
 
-def _segment_references_nas(all_segment_tokens: list[str]) -> bool:
-    return any(NAS_HOST_TOKEN_PATTERN.search(each_token) for each_token in all_segment_tokens)
+def _segment_references_nas(
+    all_segment_tokens: list[str], nas_host_pattern: re.Pattern[str]
+) -> bool:
+    return any(nas_host_pattern.search(each_token) for each_token in all_segment_tokens)
 
 
 def _segment_carries_batch_mode(all_segment_tokens: list[str]) -> bool:
@@ -114,10 +123,10 @@ def _find_nas_ssh_violation(command: str) -> str | None:
 
     ::
 
-        ssh -p 9222 jon@192.168.1.100 "ls"          flag: bare-binary message
-        "…/OpenSSH/ssh.exe" -p 9222 jon@192.168…    flag: missing-batch-mode message
+        ssh -p 22 operator@nas.example.local "ls"          flag: bare-binary message
+        "…/OpenSSH/ssh.exe" -p 22 operator@nas…    flag: missing-batch-mode message
         "…/OpenSSH/ssh.exe" -o BatchMode=yes …NAS   ok:   None
-        ssh jon@example.com "ls"                     ok:   None
+        ssh operator@example.com "ls"                     ok:   None
 
     Tokenizes the command, splits it into simple-command segments, and evaluates
     each segment whose leading program is an ssh-family word AND whose tokens carry
@@ -135,18 +144,19 @@ def _find_nas_ssh_violation(command: str) -> str | None:
         all_command_tokens = shlex.split(command)
     except ValueError:
         return None
+    nas_host_pattern = _nas_host_token_pattern()
     for each_segment in _split_into_segments(all_command_tokens):
         leading_program = _effective_leading_program(each_segment)
         if leading_program is None:
             continue
         if _token_basename(leading_program) not in ALL_SSH_FAMILY_COMMAND_BASENAMES:
             continue
-        if not _segment_references_nas(each_segment):
+        if not _segment_references_nas(each_segment, nas_host_pattern):
             continue
         if not _is_openssh_binary_path(leading_program):
-            return BARE_SSH_BINARY_MESSAGE
+            return bare_ssh_binary_deny_message()
         if not _segment_carries_batch_mode(each_segment):
-            return MISSING_BATCH_MODE_MESSAGE
+            return missing_batch_mode_deny_message()
     return None