claude-dev-env 1.51.0 → 1.52.1

package/hooks/blocking/code_rules_enforcer.py

@@ -17,7 +17,9 @@ concern focused. The separate ``tdd_enforcer.py`` hook accepts any
 """
 import json
 import sys
+from collections import Counter
 from pathlib import Path
+from typing import TextIO
 
 _BLOCKING_DIRECTORY = str(Path(__file__).resolve().parent)
 _HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
@@ -120,6 +122,11 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CODE_EXTENSIONS,
     ALL_JAVASCRIPT_EXTENSIONS,
     ALL_PYTHON_EXTENSIONS,
+    PRECHECK_USAGE_EXIT_CODE,
+    PRECHECK_USAGE_MESSAGE,
+)
+from hooks_constants.setup_project_paths_constants import (  # noqa: E402
+    UTF8_BYTE_ORDER_MARK,
 )
 
 
@@ -310,72 +317,390 @@ def prior_and_post_edit_content(
     return existing_content, existing_content.replace(old_string, new_string, 1)
 
 
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
+def _is_validated_target(file_path: str) -> bool:
+    """Return whether the path is subject to code-rules validation.
 
-    tool_name = input_data.get("tool_name", "")
-    tool_input = input_data.get("tool_input", {})
-    file_path = tool_input.get("file_path", "")
+    Args:
+        file_path: The destination path of the write, edit, or pre-check target.
 
+    Returns:
+        True when the path is non-empty, outside hook infrastructure, and
+        carries a code extension; False for every exempt path.
+    """
     if not file_path:
-        sys.exit(0)
-
+        return False
     if is_hook_infrastructure(file_path):
-        sys.exit(0)
+        return False
+    return get_file_extension(file_path) in ALL_CODE_EXTENSIONS
 
-    extension = get_file_extension(file_path)
-    if extension not in ALL_CODE_EXTENSIONS:
-        sys.exit(0)
 
-    old_content = ""
-    prior_full_file_content = ""
-    full_file_content_after_edit: str | None = None
+def _without_line_prefix(violation_text: str) -> str:
+    """Return the violation message body with its ``Line <n>: `` locator removed.
+
+    Args:
+        violation_text: A violation message, optionally carrying a leading
+            ``Line <n>: `` locator.
+
+    Returns:
+        The message body shared by fragment-scoped and full-file scans of the
+        same violation, regardless of which line numbering produced it.
+    """
+    locator, separator, message_body = violation_text.partition(": ")
+    if separator and locator.startswith("Line ") and locator[len("Line "):].isdigit():
+        return message_body
+    return violation_text
+
+
+def _forecast_full_file_violations(
+    full_file_content_after_edit: str,
+    file_path: str,
+    prior_full_file_content: str,
+    all_blocking_issues: list[str],
+) -> list[str]:
+    """Return full-file violations absent from the fragment-scoped blocking list.
+
+    Runs a complete, un-scoped scan of the whole post-edit file so fragment-scoped
+    checks see every line, then drops the violations already present in
+    ``all_blocking_issues``. Matching is line-number-agnostic with
+    per-occurrence accounting: each blocking entry consumes exactly one
+    full-file entry carrying the same message body, so a violation the fragment
+    itself introduces stays out of the forecast even though the two scans
+    number its line differently, while a second same-message violation
+    elsewhere in the file still surfaces. The remainder are the violations that
+    survive elsewhere in the file and will block a future edit.
+
+    Body matching relies on an invariant of the check suite: every check that
+    embeds a secondary source position in its message body (function length,
+    banned-noun binding spans, test isolation) scans the whole post-edit file
+    in both passes, so those embedded positions are identical across scans;
+    checks that scan only the fragment carry their position solely in the
+    strippable ``Line <n>: `` locator. A fragment-scoped check that embeds a
+    position in its body would defeat the dedup and re-list its own violation.
+
+    Args:
+        full_file_content_after_edit: The whole post-edit file content.
+        file_path: The destination path used for classification.
+        prior_full_file_content: The whole file content before the edit applied,
+            used so the comment diff reflects the real prior state.
+        all_blocking_issues: The fragment-scoped issues that already decide the
+            deny.
+
+    Returns:
+        The full-file violations not already in ``all_blocking_issues``.
+    """
+    all_full_file_issues = validate_content(
+        full_file_content_after_edit, file_path, prior_full_file_content
+    )
+    remaining_blocking_counts = Counter(
+        _without_line_prefix(each_issue) for each_issue in all_blocking_issues
+    )
+    forecast_issues: list[str] = []
+    for each_issue in all_full_file_issues:
+        message_body = _without_line_prefix(each_issue)
+        if remaining_blocking_counts[message_body] > 0:
+            remaining_blocking_counts[message_body] -= 1
+            continue
+        forecast_issues.append(each_issue)
+    return forecast_issues
+
+
+def _precheck_hint() -> str:
+    """Return the discoverability hint pointing at the script's pre-check mode."""
+    script_path = str(Path(__file__).resolve())
+    return (
+        "; Pre-check a complete candidate before retrying: "
+        f'"{sys.executable}" "{script_path}" --check <candidate> --as <target>'
+    )
+
+
+def _run_precheck(
+    candidate_path: str,
+    target_path: str,
+    violation_stream: TextIO,
+    error_stream: TextIO,
+) -> int:
+    """Validate a complete candidate file as if it lived at its destination.
+
+    Reads the candidate's full content and runs the complete verdict (no diff
+    scoping) using ``target_path`` for every path-based classification, so a
+    candidate staged in a temporary directory is judged as if written to its real
+    destination. Every leading byte-order mark on the candidate is stripped so
+    the verdict matches the one the decoded tool-payload content receives — a
+    BOM would otherwise fail AST parsing and silently skip every AST-based
+    check.
+
+    Args:
+        candidate_path: The path of the candidate file to validate.
+        target_path: The destination path used for extension dispatch and every
+            exemption decision.
+        violation_stream: The stream each violation line is written to.
+        error_stream: The stream the unreadable-candidate error line is written
+            to.
+
+    Returns:
+        Exit code 1 when any violation exists or the candidate cannot be read,
+        and 0 when the candidate is clean or the target is exempt.
+    """
+    if not _is_validated_target(target_path):
+        return 0
+    candidate_content = _read_existing_file_content(candidate_path)
+    if candidate_content is None:
+        error_stream.write(f"error: cannot read candidate file: {candidate_path}\n")
+        return 1
+    candidate_content = candidate_content.lstrip(UTF8_BYTE_ORDER_MARK)
+    old_content = _read_existing_file_content(target_path) or ""
+    all_issues = validate_content(candidate_content, target_path, old_content)
+    for each_issue in all_issues:
+        violation_stream.write(f"{each_issue}\n")
+    return 1 if all_issues else 0
+
+
+def _precheck_arguments(all_arguments: list[str]) -> tuple[str, str] | None:
+    """Parse a strict pre-check argument vector into a candidate and target pair.
+
+    Accepts exactly the two documented shapes — ``--check <candidate>`` or
+    ``--check <candidate> --as <target>`` — with the target defaulting to the
+    candidate when ``--as`` is absent. Any unrecognized or extra token, a
+    reordered flag, or a missing path value is rejected rather than silently
+    ignored, so a malformed invocation can never look like a clean verdict.
+
+    Args:
+        all_arguments: The argument vector following the script name, expected
+            to lead with ``--check``.
+
+    Returns:
+        A ``(candidate_path, target_path)`` pair for one of the two supported
+        shapes; otherwise None — the vector does not lead with ``--check``,
+        omits a path value, places a flag-shaped token where a path belongs,
+        or carries an unrecognized or extra token.
+    """
+    if not all_arguments or all_arguments[0] != "--check":
+        return None
+    tokens_after_check = all_arguments[1:]
+    if not tokens_after_check or tokens_after_check[0].startswith("--"):
+        return None
+    candidate_path = tokens_after_check[0]
+    tokens_after_candidate = tokens_after_check[1:]
+    if not tokens_after_candidate:
+        return candidate_path, candidate_path
+    if tokens_after_candidate[0] != "--as":
+        return None
+    target_tokens = tokens_after_candidate[1:]
+    if len(target_tokens) != 1 or target_tokens[0].startswith("--"):
+        return None
+    return candidate_path, target_tokens[0]
+
+
+def _run_precheck_command(
+    all_arguments: list[str],
+    violation_stream: TextIO,
+    error_stream: TextIO,
+) -> int:
+    """Run the pre-check CLI mode for an argument vector carrying ``--check``.
+
+    Args:
+        all_arguments: The argument vector following the script name.
+        violation_stream: The stream each violation line is written to.
+        error_stream: The stream usage and candidate errors are written to.
+
+    Returns:
+        The usage-error exit code for a malformed flag sequence, otherwise the
+        ``_run_precheck`` verdict for the parsed candidate and target.
+    """
+    precheck_paths = _precheck_arguments(all_arguments)
+    if precheck_paths is None:
+        error_stream.write(PRECHECK_USAGE_MESSAGE)
+        return PRECHECK_USAGE_EXIT_CODE
+    candidate_path, target_path = precheck_paths
+    return _run_precheck(candidate_path, target_path, violation_stream, error_stream)
+
+
+def _contents_for_validation(
+    tool_name: str,
+    new_string: str,
+    old_string: str,
+    written_content: str,
+    file_path: str,
+) -> tuple[str, str, str | None, str] | None:
+    """Resolve the content views the verdict needs for the given tool payload.
+
+    Args:
+        tool_name: The tool named in the PreToolUse payload.
+        new_string: The Edit payload's replacement fragment.
+        old_string: The Edit payload's fragment to replace.
+        written_content: The Write payload's whole file body.
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        A ``(content, old_content, full_file_content_after_edit,
+        prior_full_file_content)`` tuple, or None when no validatable view
+        exists — an unreadable edit target, or a write over an existing file.
+    """
     if tool_name == "Edit":
-        content = tool_input.get("new_string", "")
-        old_content = tool_input.get("old_string", "")
         prior_content, full_file_content_after_edit = prior_and_post_edit_content(
-            file_path, old_content, content,
+            file_path, old_string, new_string,
         )
-        prior_full_file_content = prior_content or ""
         if full_file_content_after_edit is None:
             full_file_content_after_edit = _read_existing_file_content(file_path)
             if full_file_content_after_edit is None:
-                sys.exit(0)
-    else:
-        content = tool_input.get("content", "") or tool_input.get("new_string", "")
-        old_content = _read_existing_file_content(file_path) or ""
+                return None
+        return new_string, old_string, full_file_content_after_edit, prior_content or ""
+    content = written_content or new_string
+    old_content = _read_existing_file_content(file_path) or ""
+    if old_content:
+        return None
+    return content, old_content, None, ""
 
-        if old_content:
-            sys.exit(0)
 
-    if not content:
-        sys.exit(0)
+def _deny_reason_for_issues(
+    all_blocking_issues: list[str],
+    tool_name: str,
+    file_path: str,
+    full_file_content_after_edit: str | None,
+    prior_full_file_content: str,
+) -> str:
+    """Compose the deny reason: blocking list, optional forecast, pre-check hint.
 
-    issues = validate_content(
+    Args:
+        all_blocking_issues: The blocking violations that decide the deny.
+        tool_name: The tool named in the PreToolUse payload.
+        file_path: The destination path used for forecast classification.
+        full_file_content_after_edit: The whole post-edit file content when the
+            edit reconstructs one, used to run the full-file forecast.
+        prior_full_file_content: The whole file content before the edit applied.
+            Empty when the edit's old_string is absent and no reliable prior
+            exists; the forecast is skipped in that case so a comment diff
+            against an empty prior cannot mislabel pre-existing comments as
+            future blockers.
+
+    Returns:
+        The complete ``permissionDecisionReason`` text.
+    """
+    issue_list = "; ".join(all_blocking_issues[:10])
+    deny_reason = (
+        f"BLOCKED: [CODE_RULES] {len(all_blocking_issues)} violation(s): {issue_list}"
+    )
+    has_reconstructed_prior = bool(prior_full_file_content)
+    if (
+        tool_name == "Edit"
+        and full_file_content_after_edit is not None
+        and has_reconstructed_prior
+    ):
+        forecast_issues = _forecast_full_file_violations(
+            full_file_content_after_edit,
+            file_path=file_path,
+            prior_full_file_content=prior_full_file_content,
+            all_blocking_issues=all_blocking_issues,
+        )
+        if forecast_issues:
+            forecast_list = "; ".join(forecast_issues[:10])
+            deny_reason += (
+                f"; FULL-FILE FORECAST — {len(forecast_issues)} additional "
+                "violation(s) elsewhere in this file will block future edits "
+                f"(full-file line numbers): {forecast_list}"
+            )
+    return deny_reason + _precheck_hint()
+
+
+def _report_blocking_violations(
+    content: str,
+    tool_name: str,
+    file_path: str,
+    old_content: str,
+    full_file_content_after_edit: str | None,
+    prior_full_file_content: str,
+    deny_stream: TextIO,
+) -> None:
+    """Run the verdict and write a deny payload when blocking violations fire.
+
+    Args:
+        content: The fragment or whole-file body under validation.
+        tool_name: The tool named in the PreToolUse payload.
+        file_path: The destination path of the write or edit.
+        old_content: The fragment the edit replaces, or empty for a write.
+        full_file_content_after_edit: The reconstructed post-edit file body,
+            or None when the payload is not an Edit.
+        prior_full_file_content: The on-disk content before the edit.
+        deny_stream: The stream the JSON deny payload is written to.
+    """
+    all_blocking_issues = validate_content(
         content,
         file_path,
         old_content,
         full_file_content_after_edit,
         prior_full_file_content,
     )
-
-    if issues:
-        issue_list = "; ".join(issues[:10])
-        deny_payload = {
-            "hookSpecificOutput": {
-                "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": f"BLOCKED: [CODE_RULES] {len(issues)} violation(s): {issue_list}",
-            }
+    if not all_blocking_issues:
+        return
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": _deny_reason_for_issues(
+                all_blocking_issues,
+                tool_name,
+                file_path,
+                full_file_content_after_edit,
+                prior_full_file_content,
+            ),
         }
-        print(json.dumps(deny_payload))
-        sys.stdout.flush()
+    }
+    deny_stream.write(json.dumps(deny_payload) + "\n")
+    deny_stream.flush()
+
 
+def main(all_arguments: list[str]) -> None:
+    """Run the enforcer for the given argument vector.
+
+    Dispatches to the pre-check CLI mode when the vector carries ``--check``;
+    otherwise reads a PreToolUse payload from stdin and emits a deny payload
+    on stdout when the content violates a blocking rule.
+
+    Args:
+        all_arguments: The argument vector following the script name.
+    """
+    if "--check" in all_arguments:
+        sys.exit(_run_precheck_command(all_arguments, sys.stdout, sys.stderr))
+
+    try:
+        pretooluse_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = pretooluse_payload.get("tool_name", "")
+    tool_input = pretooluse_payload.get("tool_input", {})
+    file_path = tool_input.get("file_path", "")
+
+    if not _is_validated_target(file_path):
+        sys.exit(0)
+
+    validation_contents = _contents_for_validation(
+        tool_name,
+        tool_input.get("new_string", ""),
+        tool_input.get("old_string", ""),
+        tool_input.get("content", ""),
+        file_path,
+    )
+    if validation_contents is None:
+        sys.exit(0)
+    content, old_content, full_file_content_after_edit, prior_full_file_content = (
+        validation_contents
+    )
+
+    if not content:
+        sys.exit(0)
+
+    _report_blocking_violations(
+        content,
+        tool_name,
+        file_path,
+        old_content,
+        full_file_content_after_edit,
+        prior_full_file_content,
+        sys.stdout,
+    )
     sys.exit(0)
 
 
 if __name__ == "__main__":
-    main()
+    main(sys.argv[1:])