claude-dev-env 1.59.0 → 1.61.0

package/hooks/blocking/code_rules_orphan_css_class.py

@@ -0,0 +1,196 @@
+"""Orphan-CSS-class check: class attributes in markup with no matching selector."""
+
+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.orphan_css_class_constants import (  # noqa: E402
+    CLASS_ATTRIBUTE_PATTERN,
+    CSS_CLASS_SELECTOR_PATTERN,
+    MAX_ORPHAN_CSS_CLASS_ISSUES,
+    MAX_SIBLING_MODULES_SCANNED,
+    ORPHAN_CSS_CLASS_MESSAGE_SUFFIX,
+    PYTHON_MODULE_GLOB,
+    STYLE_BLOCK_PATTERN,
+)
+
+
+def _string_literals_with_lines(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return every string-constant value in the tree paired with its line number.
+
+    Args:
+        tree: The parsed module to walk.
+
+    Returns:
+        A list of ``(string_value, line_number)`` pairs, one per string constant.
+    """
+    literals: list[tuple[str, int]] = []
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            literals.append((each_node.value, each_node.lineno))
+    return literals
+
+
+def _class_names_in_attribute(attribute_text: str) -> list[str]:
+    """Return the individual class names in a single ``class="..."`` attribute.
+
+    Args:
+        attribute_text: The whitespace-separated class list from one attribute.
+
+    Returns:
+        Each non-empty class token, in order.
+    """
+    return [each_token for each_token in attribute_text.split() if each_token]
+
+
+def _class_references_with_lines(
+    all_string_literals: list[tuple[str, int]],
+) -> list[tuple[str, int]]:
+    """Return every class name referenced in a ``class="..."`` attribute.
+
+    Args:
+        all_string_literals: The ``(literal_text, line_number)`` constants to scan.
+
+    Returns:
+        A list of ``(class_name, line_number)`` pairs, one per referenced class.
+    """
+    references: list[tuple[str, int]] = []
+    for each_text, each_line in all_string_literals:
+        for each_match in CLASS_ATTRIBUTE_PATTERN.finditer(each_text):
+            for each_class_name in _class_names_in_attribute(each_match.group(1)):
+                references.append((each_class_name, each_line))
+    return references
+
+
+def _defined_class_selectors(all_string_literals: list[tuple[str, int]]) -> set[str]:
+    """Return every CSS class name defined by a selector inside a ``<style>`` block.
+
+    Args:
+        all_string_literals: The ``(literal_text, line_number)`` constants to scan.
+
+    Returns:
+        The set of class names that carry a matching ``.<class>`` selector.
+    """
+    defined: set[str] = set()
+    for each_text, _ in all_string_literals:
+        for each_style_match in STYLE_BLOCK_PATTERN.finditer(each_text):
+            for each_selector in CSS_CLASS_SELECTOR_PATTERN.finditer(
+                each_style_match.group(1)
+            ):
+                defined.add(each_selector.group(1))
+    return defined
+
+
+def _sibling_module_paths(file_path: str) -> list[Path]:
+    """Return the importable sibling Python modules near *file_path*.
+
+    Scans the file's own directory and its immediate child directories, since a
+    markup module commonly imports its ``<style>`` constant from a companion
+    package directory beside it. The scan is bounded so a large tree never
+    stalls a write.
+
+    Args:
+        file_path: The absolute path of the file under validation.
+
+    Returns:
+        The sibling ``.py`` paths to read for cross-module selector resolution,
+        excluding the file itself, capped at the scan budget.
+    """
+    target = Path(file_path)
+    base_directory = target.parent
+    if not base_directory.is_dir():
+        return []
+    siblings: list[Path] = []
+    for each_path in sorted(base_directory.rglob(PYTHON_MODULE_GLOB)):
+        if each_path.resolve() == target.resolve():
+            continue
+        siblings.append(each_path)
+        if len(siblings) >= MAX_SIBLING_MODULES_SCANNED:
+            break
+    return siblings
+
+
+def _selectors_from_sibling_modules(file_path: str) -> set[str]:
+    """Return CSS class selectors defined in ``<style>`` blocks of sibling modules.
+
+    Args:
+        file_path: The absolute path of the file under validation.
+
+    Returns:
+        The union of class names whose selectors appear in any readable sibling
+        module's string literals.
+    """
+    selectors: set[str] = set()
+    for each_sibling in _sibling_module_paths(file_path):
+        try:
+            sibling_source = each_sibling.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        try:
+            sibling_tree = ast.parse(sibling_source)
+        except SyntaxError:
+            continue
+        selectors |= _defined_class_selectors(_string_literals_with_lines(sibling_tree))
+    return selectors
+
+
+def check_orphan_css_classes(content: str, file_path: str) -> list[str]:
+    """Flag ``class="..."`` markup whose class has no matching CSS selector.
+
+    A module that emits HTML names each class it references with a matching
+    ``.<class>`` selector, either in a ``<style>`` block in the same file or in
+    a companion module beside it. A referenced class with no selector anywhere
+    is a dead attribute (or a missing rule), so this flags it. The check only
+    fires for a file that itself emits markup, and only after a ``<style>``
+    block exists in the file or a sibling — a file with markup but no style
+    source nearby is left alone, since its stylesheet lives outside the scan.
+    Test files are exempt, since a fixture may carry intentional orphan markup.
+
+    Args:
+        content: The new or whole-file content being written.
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        One issue per orphan class reference, capped at the issue budget.
+    """
+    if is_test_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    all_string_literals = _string_literals_with_lines(tree)
+    class_references = _class_references_with_lines(all_string_literals)
+    if not class_references:
+        return []
+    defined_selectors = _defined_class_selectors(all_string_literals)
+    defined_selectors |= _selectors_from_sibling_modules(file_path)
+    if not defined_selectors:
+        return []
+    issues: list[str] = []
+    reported_classes: set[str] = set()
+    for each_class_name, each_line in class_references:
+        if each_class_name in defined_selectors:
+            continue
+        if each_class_name in reported_classes:
+            continue
+        reported_classes.add(each_class_name)
+        issues.append(
+            f"Line {each_line}: CSS class {each_class_name!r} used in markup"
+            f" has no matching '.{each_class_name}' selector - "
+            f"{ORPHAN_CSS_CLASS_MESSAGE_SUFFIX}"
+        )
+        if len(issues) >= MAX_ORPHAN_CSS_CLASS_ISSUES:
+            break
+    return issues

package/hooks/blocking/code_rules_typeddict_stub.py

@@ -26,6 +26,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_STUB_IMPLEMENTATION_ISSUES,
     MAX_THIN_WRAPPER_ISSUES,
     MAX_TYPED_DICT_PAIR_ISSUES,
+    MAX_ZERO_PAYLOAD_ALIAS_ISSUES,
 )
 
 def _pascal_to_snake_case(pascal_name: str) -> str:
@@ -58,6 +59,16 @@ def _collect_module_function_names(parsed_tree: ast.AST) -> set[str]:
     return module_function_names
 
 
+def _collect_module_function_nodes_by_name(
+    parsed_tree: ast.AST,
+) -> dict[str, ast.FunctionDef | ast.AsyncFunctionDef]:
+    function_node_by_name: dict[str, ast.FunctionDef | ast.AsyncFunctionDef] = {}
+    for each_statement in parsed_tree.body:
+        if isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            function_node_by_name[each_statement.name] = each_statement
+    return function_node_by_name
+
+
 def _is_init_file(file_path: str) -> bool:
     return file_path.replace("\\", "/").rsplit("/", 1)[-1] == "__init__.py"
 
@@ -126,6 +137,167 @@ def check_thin_wrapper_files(content: str, file_path: str) -> list[str]:
     return issues[:MAX_THIN_WRAPPER_ISSUES]
 
 
+def _function_parameter_names_in_order(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+    arguments = function_node.args
+    positional_arguments = [*arguments.posonlyargs, *arguments.args]
+    return [each_argument.arg for each_argument in positional_arguments]
+
+
+def _has_only_positional_parameters(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    arguments = function_node.args
+    has_no_parameter_defaults = not arguments.defaults and not arguments.kw_defaults
+    return (
+        not arguments.kwonlyargs
+        and arguments.vararg is None
+        and arguments.kwarg is None
+        and has_no_parameter_defaults
+    )
+
+
+def _single_return_call(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> ast.Call | None:
+    body_statements = function_node.body
+    statements_after_docstring = (
+        body_statements[1:]
+        if body_statements and _statement_is_docstring(body_statements[0])
+        else body_statements
+    )
+    if len(statements_after_docstring) != 1:
+        return None
+    only_statement = statements_after_docstring[0]
+    if not isinstance(only_statement, ast.Return):
+        return None
+    return only_statement.value if isinstance(only_statement.value, ast.Call) else None
+
+
+def _forwards_parameters_unchanged(call_node: ast.Call, all_parameter_names: list[str]) -> bool:
+    if call_node.keywords:
+        return False
+    if len(call_node.args) != len(all_parameter_names):
+        return False
+    for each_argument, each_parameter_name in zip(call_node.args, all_parameter_names):
+        if not isinstance(each_argument, ast.Name) or each_argument.id != each_parameter_name:
+            return False
+    return True
+
+
+def _function_is_async(function_node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    return isinstance(function_node, ast.AsyncFunctionDef)
+
+
+def _alias_target_name(call_node: ast.Call, all_sibling_function_names: set[str]) -> str:
+    callee = call_node.func
+    if not isinstance(callee, ast.Name):
+        return ""
+    return callee.id if callee.id in all_sibling_function_names else ""
+
+
+def _module_string_literal_values(parsed_tree: ast.AST) -> set[str]:
+    string_literal_values: set[str] = set()
+    for each_node in ast.walk(parsed_tree):
+        if isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            string_literal_values.add(each_node.value)
+    return string_literal_values
+
+
+def _target_accepts_forwarded_positional_call(
+    target_node: ast.FunctionDef | ast.AsyncFunctionDef,
+    forwarded_argument_count: int,
+) -> bool:
+    arguments = target_node.args
+    if any(default is None for default in arguments.kw_defaults):
+        return False
+    positional_parameters = [*arguments.posonlyargs, *arguments.args]
+    total_positional_count = len(positional_parameters)
+    required_positional_count = total_positional_count - len(arguments.defaults)
+    if arguments.vararg is not None:
+        return forwarded_argument_count >= required_positional_count
+    return required_positional_count <= forwarded_argument_count <= total_positional_count
+
+
+def check_zero_payload_function_alias(content: str, file_path: str) -> list[str]:
+    """Flag a module-level function that only forwards its parameters to a sibling.
+
+    A function whose entire body (after an optional docstring) is a single
+    `return sibling_function(first_param, second_param, ...)` that forwards its
+    own parameters unchanged to another function defined in the same module is a
+    second name for one behavior — indirection without payload, which CODE_RULES
+    discourages. Callers should invoke the sibling directly. Both `def` and
+    `async def` forwarders are inspected.
+
+    A forwarder is left unflagged when any of these makes a direct call to the
+    target not equivalent to the alias: a decorator (caching, `@property`, route
+    registration); a parameter carrying a default value the target rejects; a
+    keyword-only / `*args` / `**kwargs` parameter on the alias; an awaitability
+    mismatch where one of the alias and target is `async def` and the other is
+    not; a forwarded positional call the live target's signature rejects (the
+    target has a keyword-only parameter without a default, or its positional
+    arity does not admit the forwarded argument count); or a name dispatched by a
+    string literal elsewhere in the module, where the named handler must exist for
+    a registry to resolve it.
+
+    Hook infrastructure is intentionally NOT exempt — pass-through aliases inside
+    hook modules are the motivating case. Test files and config files are exempt
+    because re-binding aliases are legitimate scaffolding there.
+
+    Args:
+        content: The source under inspection.
+        file_path: Path to the file, used for the test and config exemptions.
+
+    Returns:
+        One issue string per pass-through alias, capped at
+        MAX_ZERO_PAYLOAD_ALIAS_ISSUES.
+    """
+    if is_test_file(file_path) or is_config_file(file_path):
+        return []
+
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+
+    function_node_by_name = _collect_module_function_nodes_by_name(parsed_tree)
+    all_sibling_function_names = set(function_node_by_name)
+    all_string_literal_values = _module_string_literal_values(parsed_tree)
+    issues: list[str] = []
+    for each_statement in parsed_tree.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if each_statement.decorator_list:
+            continue
+        if each_statement.name in all_string_literal_values:
+            continue
+        if not _has_only_positional_parameters(each_statement):
+            continue
+        call_node = _single_return_call(each_statement)
+        if call_node is None:
+            continue
+        target_name = _alias_target_name(call_node, all_sibling_function_names)
+        if not target_name or target_name == each_statement.name:
+            continue
+        target_node = function_node_by_name[target_name]
+        if _function_is_async(each_statement) != _function_is_async(target_node):
+            continue
+        forwarded_parameter_names = _function_parameter_names_in_order(each_statement)
+        if not _forwards_parameters_unchanged(call_node, forwarded_parameter_names):
+            continue
+        if not _target_accepts_forwarded_positional_call(
+            target_node, len(forwarded_parameter_names)
+        ):
+            continue
+        issues.append(
+            f"Line {each_statement.lineno}: {file_path}: zero-payload alias — "
+            f"{each_statement.name} only forwards its parameters to {target_name}; "
+            f"callers should call {target_name} directly (indirection without payload)"
+        )
+    return issues[:MAX_ZERO_PAYLOAD_ALIAS_ISSUES]
+
+
 def check_typed_dict_encode_decode(content: str, file_path: str) -> list[str]:
     """Flag TypedDict declarations missing companion `_encode_*` / `_decode_*` functions."""
     if (

package/hooks/blocking/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration package for the blocking hooks.
+
+A regular package (not a namespace package) so it resolves ahead of any
+same-named package later on ``sys.path``.
+"""

package/hooks/blocking/config/verified_commit_constants.py

@@ -0,0 +1,118 @@
+"""Constants for the verified-commit gate hook family.
+
+Shared by ``verification_verdict_store.py``, ``verified_commit_gate.py``,
+and ``verifier_verdict_minter.py`` so every tunable lives in one place.
+"""
+
+from __future__ import annotations
+
+GIT_TIMEOUT_SECONDS = 30
+ROOT_KEY_HEX_LENGTH = 16
+VERDICT_JSON_INDENT = 2
+CLAUDE_HOME_DIRECTORY_NAME = ".claude"
+VERDICT_DIRECTORY_NAME = "verification"
+VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN = r"['\"\\/,\s]+"
+VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN = r"(?=['\"]*[\\/,])"
+RELATIVE_VERDICT_DIRECTORY_PATTERN = r"(?:^|(?<=[\s;&|(='\"]))verification[\\/]"
+VERDICT_PATH_GLUE_PATTERN = r"['\"+\\/\s]*[\\/]['\"+\\/\s]*"
+VERDICT_DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?verification[\\/]?['\"]?(?=[\s;&|]|$)"
+VERDICT_PATH_JOINED_VARIABLE_PATTERN = r"\$\{?(\w+)\}?[\\/]|[\\/]\$\{?(\w+)\}?"
+VERDICT_PATH_VARIABLE_ASSIGNMENT_PATTERN = r"(?:^|(?<=[\s;&|(]))%s=(\S+)"
+VERDICT_FILE_RELATIVE_REFERENCE_PATTERN = (
+    rf"(?:^|(?<=[\s;&|(='\"\\/]))verification[\\/][0-9a-f]{{{ROOT_KEY_HEX_LENGTH}}}\.json"
+)
+PATH_OBFUSCATION_PRIMITIVE_PATTERN = (
+    r"chr\s*\(|bytes\.fromhex\s*\(|b64decode\s*\(|codecs\.decode\s*\("
+    r"|(?:bytes|bytearray)\s*\(\s*\[|\[char\[?\]?\]"
+)
+ALL_VERDICT_PATH_SEGMENT_NAMES = (".claude", "verification")
+ALL_VERDICT_PATH_SEGMENT_BODIES = ("claude", "verification")
+HEX_TOKEN_PATTERN = r"(?<![0-9a-fx])([0-9a-f]{6,})(?![0-9a-f])"
+BASE64_TOKEN_PATTERN = r"[A-Za-z0-9+/]{8,}={0,2}"
+CHARACTER_CODE_SEQUENCE_PATTERN = r"\d{1,3}(?:\s*,\s*\d{1,3})+"
+CHR_CALL_CHAIN_PATTERN = r"chr\(\s*\d{1,3}\s*\)(?:\s*\+\s*chr\(\s*\d{1,3}\s*\))+"
+CHR_CALL_CODE_PATTERN = r"chr\(\s*(\d{1,3})\s*\)"
+HEX_DIGITS_PER_BYTE = 2
+FILE_WRITE_PRIMITIVE_PATTERN = (
+    r"\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b|>"
+)
+NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN = (
+    r"\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b"
+)
+WRITE_CALL_REGION_PATTERN = (
+    r"(?:\bopen\s*\(|\.write_text\s*\(|\.write_bytes\s*\("
+    r"|Out-File|Set-Content|Add-Content|\btee\b)[^;&|\n]*"
+)
+VERDICT_KEY_ALL_PASS = "all_pass"
+VERDICT_KEY_MANIFEST_SHA256 = "manifest_sha256"
+VERDICT_KEY_FINDINGS = "findings"
+SUBAGENTS_DIRECTORY_NAME = "subagents"
+AGENT_TRANSCRIPT_GLOB = "agent-*.jsonl"
+AGENT_META_SIDECAR_SUFFIX = ".meta.json"
+AGENT_META_TYPE_KEY = "agentType"
+TRANSCRIPT_ENTRY_TYPE_KEY = "type"
+TRANSCRIPT_ASSISTANT_ENTRY_TYPE = "assistant"
+TRANSCRIPT_MESSAGE_KEY = "message"
+TRANSCRIPT_CONTENT_KEY = "content"
+TRANSCRIPT_CONTENT_TYPE_KEY = "type"
+TRANSCRIPT_TEXT_CONTENT_TYPE = "text"
+TRANSCRIPT_TEXT_KEY = "text"
+VERDICT_FENCE_PATTERN = r"```verdict\s*\n(.*?)```"
+MANIFEST_HASH_CLI_FLAG = "--manifest-hash"
+DOCS_ONLY_EXTENSIONS = frozenset(
+    {".md", ".txt", ".rst", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico"}
+)
+PYTHON_EXTENSION = ".py"
+TEST_FILE_PREFIX = "test_"
+TEST_FILE_SUFFIX = "_test.py"
+CONFTEST_FILE_NAME = "conftest.py"
+MINIMUM_STATUS_FIELD_COUNT = 2
+ALL_FALLBACK_BASE_REFERENCES = ("origin/main", "origin/master")
+ALL_TOOLING_STATE_PREFIXES = (
+    ".claude/verification/",
+    ".claude/worktrees/",
+    ".claude/daemon/",
+    ".claude/teams/",
+    ".claude/sessions/",
+    ".cursor/worktrees/",
+)
+GATED_GIT_SUBCOMMANDS = frozenset({"commit", "push"})
+ALL_GIT_BINARY_NAMES = frozenset({"git", "git.exe"})
+VALUE_TAKING_GIT_OPTIONS = frozenset({"-C", "-c", "--git-dir", "--work-tree", "--namespace"})
+REPO_DIRECTORY_OPTION = "-C"
+WORK_TREE_OPTION = "--work-tree"
+DIRECTORY_CHANGE_VERBS = frozenset({"cd", "pushd", "set-location", "sl"})
+DIRECTORY_CHANGE_PATH_OPTIONS = frozenset({"-path", "-literalpath"})
+DIRECTORY_CHANGE_OPTION_TERMINATOR = "--"
+DIRECTORY_CHANGE_PATTERN_PREFIX = r"(?:^|(?<=[\s;&|(]))(?:"
+DIRECTORY_CHANGE_PATTERN_SUFFIX = r")(?=\s|$)"
+DIRECTORY_CHANGE_OPTION_PREFIX_PATTERN = r"(?:[ \t]+(?:%s)(?=\s|$))*"
+DIRECTORY_CHANGE_TARGET_PATTERN = r"[ \t]+['\"]?\S*"
+CLAUDE_HOME_TARGET_BOUNDARY_PATTERN = r"[\\/]?['\"]?(?=[\s;&|]|$)"
+VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN = r"[\\/]?['\"]?(?=[\s;&|]|$)"
+COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN = r"[;&|\n][\s]*\S"
+OPTION_WITH_VALUE_STEP = 2
+ALL_GATED_TOOL_NAMES = ("Bash", "PowerShell")
+HASH_PREVIEW_LENGTH = 16
+MINTING_AGENT_TYPE = "code-verifier"
+VERDICT_DIRECTORY_GUARD_MESSAGE = (
+    "BLOCKED: [VERDICT_DIRECTORY_GUARD] Shell access to the verification "
+    "verdict directory (~/.claude/verification/) is denied. Only the "
+    "verifier_verdict_minter.py SubagentStop hook writes verdict files; a "
+    "shell write here would forge a passing verdict and defeat the "
+    "verified-commit gate. Spawn the code-verifier agent to earn a verdict "
+    "instead of writing one."
+)
+CORRECTIVE_MESSAGE = (
+    "BLOCKED: [VERIFIED_COMMIT_GATE] This branch surface has no passing "
+    "verification verdict. Spawn the code-verifier agent (Agent tool, "
+    "subagent_type 'code-verifier') with the task texts, the diff scope, "
+    "and recorded baselines; when it finishes with a clean verdict the "
+    "SubagentStop hook mints the verdict and this command will pass. Any "
+    "file change after verification invalidates the verdict, so verify "
+    "last. Exempt automatically: docs/image files, pytest test files, and "
+    "Python files whose docstring- and comment-stripped AST is unchanged "
+    "(comment-only edits in non-Python files are not exempt)."
+)