claude-dev-env 2.12.0 → 2.14.0

package/hooks/blocking/pr_description_command_parser.py

@@ -1,237 +0,0 @@
-"""Parse gh pr create/edit/comment commands into auditable body content.
-
-Tokenizes the captured shell command and extracts the PR body that should be
-audited, resolving body-file paths and rejecting unauditable shell variables,
-stdin sentinels, and path-traversal targets. Positional PR-number extraction
-lives in pr_description_pr_number.py.
-"""
-
-import shlex
-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 blocking._gh_body_arg_utils import (  # noqa: E402
-    all_body_flags,
-    body_file_flag,
-    body_file_short_flag,
-    count_extra_tokens_to_skip_for_split_quoted_value,
-    get_logical_first_line,
-    is_flag_shaped_token,
-    is_unresolvable_shell_value,
-    iter_significant_tokens,
-    match_body_file_equals_prefix,
-    match_body_flag_equals_prefix,
-    match_non_body_value_flag_equals_prefix,
-    non_body_value_flags,
-    strip_surrounding_quotes,
-)
-from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
-    BODY_FILE_STDIN_SENTINEL,
-)
-from hooks_constants.setup_project_paths_constants import UTF8_ENCODING  # noqa: E402
-
-
-class PathTraversalError(Exception):
-    pass
-
-
-def _read_body_file_contents(file_path: str) -> str | None:
-    given_path = Path(file_path)
-    allowed_root = Path.cwd().resolve()
-    if given_path.is_symlink():
-        resolved_target = given_path.resolve()
-        try:
-            resolved_target.relative_to(allowed_root)
-        except ValueError as traversal_error:
-            raise PathTraversalError(
-                "symlink target resolves outside allowed root"
-            ) from traversal_error
-    resolved_path = given_path.resolve()
-    if not given_path.is_absolute():
-        try:
-            resolved_path.relative_to(allowed_root)
-        except ValueError as traversal_error:
-            raise PathTraversalError(
-                "relative path resolves outside allowed root"
-            ) from traversal_error
-    try:
-        with open(resolved_path, "r", encoding=UTF8_ENCODING, errors="replace") as body_file:
-            return body_file.read()
-    except (FileNotFoundError, IsADirectoryError, PermissionError, OSError):
-        return None
-
-
-def _resolve_body_file_value(raw_value_token: str) -> str | None:
-    """Return file contents, or None when the body cannot be audited.
-
-    None means body is present but unauditable -- skip enforcement.
-    This covers: stdin sentinel, unresolvable shell variables, and path-traversal-rejected paths.
-    """
-    stripped_value = strip_surrounding_quotes(raw_value_token)
-    if not stripped_value:
-        return None
-    if stripped_value == BODY_FILE_STDIN_SENTINEL:
-        return None
-    if is_unresolvable_shell_value(stripped_value):
-        return None
-    try:
-        return _read_body_file_contents(stripped_value)
-    except PathTraversalError:
-        return None
-
-
-def _resolve_body_string_value(raw_value_token: str) -> str | None:
-    """Return the literal body string, or None when the value is an
-    unresolvable shell variable.
-
-    Distinguishing the two cases lets `pr_description_enforcer.main()` skip enforcement only for
-    unauditable bodies; a literal `--body ""` still returns `""` and flows
-    into `validate_pr_body` so the substantive-prose check blocks it.
-    """
-    stripped_value = strip_surrounding_quotes(raw_value_token)
-    if is_unresolvable_shell_value(stripped_value):
-        return None
-    return stripped_value
-
-
-def _reassemble_split_quoted_value(
-    first_value_token: str, all_remaining_tokens: list[str]
-) -> str | None:
-    extra_tokens_consumed = count_extra_tokens_to_skip_for_split_quoted_value(
-        all_remaining_tokens,
-        first_value_token,
-    )
-    if extra_tokens_consumed is None:
-        return None
-    if extra_tokens_consumed == 0:
-        return first_value_token
-    continuation_tokens = all_remaining_tokens[:extra_tokens_consumed]
-    return " ".join([first_value_token, *continuation_tokens])
-
-
-def _scan_raw_tokens_for_body(all_raw_tokens: list[str]) -> str | None | bool:
-    """Return the body value from a raw token list, or False if no body flag found.
-
-    Returns False when no body/body-file flag is present (caller should continue).
-    Returns None when a body-file flag is present but malformed (no value
-    follows), OR when the body value is an unresolvable shell variable (e.g.
-    `--body "$VAR"`) — in either case the body is unauditable and the caller
-    skips enforcement.
-    Returns str for resolved body string values. An empty string `""` is a
-    literal-empty body (e.g. `--body ""`) and must still flow into
-    `validate_pr_body` so the substantive-prose check blocks it.
-    """
-    token_index = 0
-    while token_index < len(all_raw_tokens):
-        current_token = all_raw_tokens[token_index]
-        remaining_raw = all_raw_tokens[token_index + 1 :]
-        non_body_equals_prefix = match_non_body_value_flag_equals_prefix(current_token)
-        if non_body_equals_prefix is not None:
-            first_value_token = current_token[len(non_body_equals_prefix) :]
-            extra_skip = count_extra_tokens_to_skip_for_split_quoted_value(
-                remaining_raw, first_value_token
-            )
-            token_index += 1 + (extra_skip or 0)
-            continue
-        if current_token in non_body_value_flags:
-            if remaining_raw and not is_flag_shaped_token(remaining_raw[0]):
-                first_value_token = remaining_raw[0]
-                extra_skip = count_extra_tokens_to_skip_for_split_quoted_value(
-                    remaining_raw[1:], first_value_token
-                )
-                token_index += 1 + 1 + (extra_skip or 0)
-                continue
-            token_index += 1
-            continue
-        body_equals_prefix = match_body_flag_equals_prefix(current_token)
-        if body_equals_prefix is not None:
-            first_value_token = current_token[len(body_equals_prefix) :]
-            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw)
-            if full_value_token is None:
-                return None
-            return _resolve_body_string_value(full_value_token)
-        body_file_equals_prefix = match_body_file_equals_prefix(current_token)
-        if body_file_equals_prefix is not None:
-            first_value_token = current_token[len(body_file_equals_prefix) :]
-            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw)
-            if full_value_token is None:
-                return None
-            return _resolve_body_file_value(full_value_token)
-        if current_token in all_body_flags:
-            if not remaining_raw or is_flag_shaped_token(remaining_raw[0]):
-                return None
-            first_value_token = remaining_raw[0]
-            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw[1:])
-            if full_value_token is None:
-                return None
-            return _resolve_body_string_value(full_value_token)
-        if current_token in {body_file_flag, body_file_short_flag}:
-            if not remaining_raw or is_flag_shaped_token(remaining_raw[0]):
-                return None
-            first_value_token = remaining_raw[0]
-            full_value_token = _reassemble_split_quoted_value(first_value_token, remaining_raw[1:])
-            if full_value_token is None:
-                return None
-            return _resolve_body_file_value(full_value_token)
-        token_index += 1
-    return False
-
-
-def extract_body_from_command(
-    command: str,
-    all_pre_tokenized: tuple[str, list[str]] | None = None,
-) -> str | None:
-    """Return the PR body content for validation, or None if unextractable.
-
-    Uses iter_significant_tokens to skip values of non-body value-taking flags
-    so that --body/--body-file embedded in a quoted --title value never false-matches.
-    For space-form body-file flags, scans the raw token list directly because
-    iter_significant_tokens consumes the value token (yielding remaining-after-value).
-
-    If all_pre_tokenized is provided as (logical_line, raw_tokens), reuses those instead
-    of recomputing the logical line and shlex split a second time.
-    """
-    if all_pre_tokenized is not None:
-        logical_line, all_raw_tokens = all_pre_tokenized
-    else:
-        logical_line = get_logical_first_line(command)
-        if not logical_line:
-            return None
-        try:
-            all_raw_tokens = shlex.split(logical_line, posix=False)
-        except ValueError:
-            return None
-    try:
-        all_significant_tokens = list(
-            iter_significant_tokens(command, pre_tokenized=(logical_line, all_raw_tokens))
-        )
-    except ValueError:
-        return None
-
-    significant_token_set = {each_token for each_token, _ in all_significant_tokens}
-    body_flag_found_in_significant = (
-        any(each_token in all_body_flags for each_token in significant_token_set)
-        or any(
-            match_body_flag_equals_prefix(each_token) is not None
-            for each_token in significant_token_set
-        )
-        or any(
-            match_body_file_equals_prefix(each_token) is not None
-            for each_token in significant_token_set
-        )
-        or any(
-            each_token in {body_file_flag, body_file_short_flag}
-            for each_token in significant_token_set
-        )
-    )
-    if not body_flag_found_in_significant:
-        return None
-
-    scan_outcome = _scan_raw_tokens_for_body(all_raw_tokens)
-    if isinstance(scan_outcome, bool):
-        return None
-    return scan_outcome

package/hooks/blocking/pr_description_enforcer.py

@@ -1,227 +0,0 @@
-"""PreToolUse hook gating gh pr create/edit/comment bodies and gh pr ready.
-
-Reads a PreToolUse JSON payload on stdin, audits body-carrying gh pr
-create/edit/comment invocations against the Anthropic claude-code style
-rules plus the proof-of-work audit for proof-shaped comment bodies, and
-denies gh pr ready while the PR carries no passing proof comment.
-Readability-management CLI flags short-circuit the stdin path to adjust
-the persisted readability state.
-"""
-
-import json
-import os
-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 blocking.pr_description_body_audit import (  # noqa: E402
-    _body_contains_any_header,
-    _compute_pr_body_shape,
-    _count_substantive_prose_chars,
-    _extract_vague_scan_text,
-    _iter_section_headers,
-    _matches_self_closing_reference,
-    _opens_with_this_pr_phrase,
-)
-from blocking.pr_description_command_parser import (  # noqa: E402
-    extract_body_from_command,
-)
-from blocking.pr_description_pr_number import (  # noqa: E402
-    _command_carries_body_flag,
-    _extract_pr_number_from_command,
-)
-from blocking.pr_description_proof_of_work import (  # noqa: E402
-    audit_proof_comment_body,
-    evaluate_pr_ready_gate,
-    is_pr_ready_command,
-    is_proof_shaped_body,
-)
-from blocking.pr_description_readability import (  # noqa: E402
-    _build_readability_escape_hatch_message,
-    _dispatch_cli_flag,
-    _evaluate_readability_metrics,
-    _extract_readability_target_text,
-    _increment_strike_count,
-    _is_readability_enabled,
-    _load_readability_thresholds,
-)
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
-    ALL_HEAVY_OPENING_HEADERS,
-    ALL_HEAVY_TESTING_HEADERS,
-    ALL_READABILITY_CLI_FLAG_TOKENS,
-    HEAVY_SHAPE,
-    MINIMUM_SUBSTANTIVE_PROSE_CHARS,
-    PR_GUIDE_PATH,
-    READABILITY_STRIKE_THRESHOLD,
-    SELF_CLOSING_REFERENCE_MESSAGE_PREFIX,
-    SELF_CLOSING_REFERENCE_MESSAGE_SUFFIX,
-    TRIVIAL_BODY_CHAR_THRESHOLD,
-    VAGUE_LANGUAGE_PATTERN,
-)
-
-
-def validate_pr_body(body: str, pr_number: int | None = None) -> list[str]:
-    """Audit a PR body against the Anthropic claude-code style rules.
-
-    Args:
-        body: The PR body markdown text to audit.
-        pr_number: The PR number when known (gh pr edit / gh pr comment); None at gh pr create time.
-
-    Returns:
-        A list of human-readable violation messages. Empty when the body passes.
-    """
-    violations: list[str] = []
-
-    substantive_chars = _count_substantive_prose_chars(body)
-    if substantive_chars < MINIMUM_SUBSTANTIVE_PROSE_CHARS:
-        violations.append(
-            "PR body lacks substantive prose -- include a Why paragraph or "
-            "substantive explanation, not only headers and bullets"
-        )
-
-    body_shape = _compute_pr_body_shape(body)
-
-    if body_shape == HEAVY_SHAPE:
-        if not _body_contains_any_header(body, ALL_HEAVY_OPENING_HEADERS):
-            violations.append(
-                f"Heavy PR body missing required opening header -- add one of "
-                f"{sorted(ALL_HEAVY_OPENING_HEADERS)}"
-            )
-        if not _body_contains_any_header(body, ALL_HEAVY_TESTING_HEADERS):
-            violations.append(
-                f"Heavy PR body missing required testing-category header -- add one of "
-                f"{sorted(ALL_HEAVY_TESTING_HEADERS)}"
-            )
-
-    body_has_any_header = len(_iter_section_headers(body)) > 0
-    body_is_trivial_sized = substantive_chars < TRIVIAL_BODY_CHAR_THRESHOLD
-    if body_has_any_header and body_is_trivial_sized:
-        violations.append(
-            "Trivial PR body contains a ceremony header -- drop every header "
-            "and write the one-sentence body directly"
-        )
-
-    if pr_number is not None and _matches_self_closing_reference(body, pr_number):
-        violations.append(
-            f"{SELF_CLOSING_REFERENCE_MESSAGE_PREFIX}{pr_number}{SELF_CLOSING_REFERENCE_MESSAGE_SUFFIX}"
-        )
-
-    if _opens_with_this_pr_phrase(body):
-        violations.append(
-            "PR body opens with 'This PR ...' -- open with an imperative verb "
-            "(Adds, Fixes, Updates, Removes, Tightens, Ports)"
-        )
-
-    vague_scan_text = _extract_vague_scan_text(body)
-    vague_matches = VAGUE_LANGUAGE_PATTERN.findall(vague_scan_text)
-    if vague_matches:
-        violations.append(
-            f"Vague language detected: {', '.join(vague_matches)} -- "
-            "be specific about what changed and why"
-        )
-
-    if _is_readability_enabled():
-        thresholds = _load_readability_thresholds()
-        target_text = _extract_readability_target_text(body)
-        metric_violations = _evaluate_readability_metrics(target_text, thresholds)
-        if metric_violations:
-            post_increment_count = _increment_strike_count()
-            if post_increment_count >= READABILITY_STRIKE_THRESHOLD:
-                violations.append(_build_readability_escape_hatch_message())
-            else:
-                violations.extend(metric_violations)
-
-    return violations
-
-
-def _emit_denial(denial_reason: str) -> None:
-    """Print the PreToolUse deny payload for a violation and log the block.
-
-    Args:
-        denial_reason: The permissionDecisionReason text for the deny payload.
-    """
-    denial_payload = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": denial_reason,
-        }
-    }
-    log_hook_block(
-        calling_hook_name="pr_description_enforcer.py",
-        hook_event="PreToolUse",
-        block_reason=denial_reason,
-    )
-    print(json.dumps(denial_payload))
-    sys.stdout.flush()
-
-
-def main() -> None:
-    for each_argv_token in sys.argv[1:]:
-        if each_argv_token in ALL_READABILITY_CLI_FLAG_TOKENS:
-            _dispatch_cli_flag(
-                each_argv_token,
-                output_stream=sys.stdout,
-                error_stream=sys.stderr,
-            )
-            return
-
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    tool_name = input_data.get("tool_name", "")
-    if tool_name != "Bash":
-        sys.exit(0)
-
-    command = input_data.get("tool_input", {}).get("command", "")
-    if not command:
-        sys.exit(0)
-
-    if is_pr_ready_command(command):
-        ready_denial_reason = evaluate_pr_ready_gate(command)
-        if ready_denial_reason is not None:
-            _emit_denial(ready_denial_reason)
-        sys.exit(0)
-
-    has_any_body_flag = _command_carries_body_flag(command)
-    is_pr_create = "gh pr create" in command and has_any_body_flag
-    is_pr_edit = "gh pr edit" in command and has_any_body_flag
-    is_pr_comment = "gh pr comment" in command and has_any_body_flag
-
-    if not (is_pr_create or is_pr_edit or is_pr_comment):
-        sys.exit(0)
-
-    body = extract_body_from_command(command)
-
-    if body is None:
-        sys.exit(0)
-
-    extracted_pr_number = None
-    if is_pr_edit or is_pr_comment:
-        extracted_pr_number = _extract_pr_number_from_command(command)
-
-    violations = validate_pr_body(body, pr_number=extracted_pr_number)
-
-    if is_pr_comment and is_proof_shaped_body(body):
-        violations.extend(audit_proof_comment_body(body, extracted_pr_number))
-
-    if violations:
-        violation_list = "; ".join(violations)
-        pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
-        _emit_denial(
-            f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
-            f"Rewrite the body yourself in Anthropic claude-code style. "
-            f"Guide:{pr_guide_reference}"
-        )
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/blocking/pr_description_pr_number.py

@@ -1,155 +0,0 @@
-"""Detect body flags and recover the positional PR number from a gh command.
-
-Reports whether a captured shell command carries any body or body-file flag,
-and extracts the positional PR number (bare integer or GitHub PR URL) from a
-gh pr edit/comment/ready command while skipping value-taking flags and their
-values.
-"""
-
-import re
-import shlex
-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 blocking._gh_body_arg_utils import (  # noqa: E402
-    all_body_flags,
-    body_file_flag,
-    body_file_short_flag,
-    count_extra_tokens_to_skip_for_split_quoted_value,
-    get_logical_first_line,
-    is_flag_shaped_token,
-    is_unresolvable_shell_value,
-    match_body_file_equals_prefix,
-    match_body_flag_equals_prefix,
-    match_non_body_value_flag_equals_prefix,
-    non_body_value_flags,
-    strip_surrounding_quotes,
-)
-from hooks_constants.pr_description_enforcer_constants import (  # noqa: E402
-    ALL_PR_NUMBER_BEARING_GH_PR_SUBCOMMANDS,
-    GH_PR_COMMAND_MIN_TOKEN_COUNT,
-)
-
-
-def _resolve_positional_pr_number(token: str) -> int | None:
-    """Return the PR number named by a positional token, or None if it is not one.
-
-    Accepts either a bare integer literal or a GitHub PR URL whose final path
-    segment is ``/pull/<number>``. The token may carry surrounding quotes;
-    unresolvable shell variables are rejected.
-    """
-    stripped_candidate = strip_surrounding_quotes(token)
-    if is_unresolvable_shell_value(stripped_candidate):
-        return None
-    url_match = re.match(
-        r"^https?://[^/]+/[^/]+/[^/]+/pull/(\d+)(?:[/?#].*)?$",
-        stripped_candidate,
-    )
-    if url_match is not None:
-        try:
-            return int(url_match.group(1))
-        except ValueError:
-            return None
-    try:
-        return int(stripped_candidate)
-    except ValueError:
-        return None
-
-
-def _extract_pr_number_from_command(command: str) -> int | None:
-    """Return the PR number positional argument from a `gh pr edit|comment|ready` command.
-
-    Skips value-taking non-body flags (and their value tokens) so that ``--repo owner/r``
-    pairs do not consume the trailing PR number. Accepts both a bare integer literal
-    and a GitHub PR URL (``https://github.com/o/r/pull/<n>``) in the positional slot.
-
-    Args:
-        command: The raw shell command captured by the hook.
-
-    Returns:
-        The PR number when one positional value (integer or URL) is present, else None.
-    """
-    logical_line = get_logical_first_line(command)
-    if not logical_line:
-        return None
-    try:
-        all_tokens = shlex.split(logical_line, posix=False)
-    except ValueError:
-        return None
-    if len(all_tokens) < GH_PR_COMMAND_MIN_TOKEN_COUNT:
-        return None
-    if all_tokens[0] != "gh" or all_tokens[1] != "pr":
-        return None
-    subcommand_token = all_tokens[2]
-    if subcommand_token not in ALL_PR_NUMBER_BEARING_GH_PR_SUBCOMMANDS:
-        return None
-    all_value_taking_bare_flags: frozenset[str] = (
-        non_body_value_flags | all_body_flags | {body_file_flag, body_file_short_flag}
-    )
-    token_index = GH_PR_COMMAND_MIN_TOKEN_COUNT
-    while token_index < len(all_tokens):
-        current_token = all_tokens[token_index]
-        matched_equals_prefix = (
-            match_non_body_value_flag_equals_prefix(current_token)
-            or match_body_flag_equals_prefix(current_token)
-            or match_body_file_equals_prefix(current_token)
-        )
-        if matched_equals_prefix is not None:
-            first_value_token = current_token[len(matched_equals_prefix) :]
-            remaining_raw_tokens = all_tokens[token_index + 1 :]
-            extra_skip = (
-                count_extra_tokens_to_skip_for_split_quoted_value(
-                    remaining_raw_tokens, first_value_token
-                )
-                or 0
-            )
-            token_index += 1 + extra_skip
-            continue
-        if current_token in all_value_taking_bare_flags:
-            token_index += 1
-            if token_index < len(all_tokens):
-                token_index += 1
-            continue
-        if is_flag_shaped_token(current_token):
-            token_index += 1
-            continue
-        resolved_pr_number = _resolve_positional_pr_number(current_token)
-        if resolved_pr_number is not None:
-            return resolved_pr_number
-        return None
-    return None
-
-
-def _command_carries_body_flag(command: str) -> bool:
-    """Return True when the command string carries any body or body-file flag.
-
-    Detects the body/body-file forms accepted by ``gh pr {create,edit,comment}``:
-
-    - Long flags: a single ``"--body" in command`` substring check catches
-      every long form — ``--body``, ``--body=<value>``, ``--body-file``, and
-      ``--body-file=<value>`` — because ``--body`` is a prefix of
-      ``--body-file``. No separate ``--body-file`` check is needed.
-    - Short flags, space-separated: ``-b <value>``, ``-F <value>`` — matched
-      as `` -b `` and `` -F `` so the literal substring cannot collide with a
-      surrounding token (e.g. ``-base``, ``-Foo``).
-    - Short flags, equal-attached: ``-b=<value>``, ``-F=<value>`` — matched
-      as `` -b=`` and `` -F=`` for the same anti-collision reason. The test
-      suite relies on this detection path.
-
-    Args:
-        command: The raw shell command captured by the hook.
-
-    Returns:
-        True if any documented body or body-file flag appears in the command.
-    """
-    return (
-        "--body" in command
-        or " -b " in command
-        or " -b=" in command
-        or " -F " in command
-        or " -F=" in command
-    )