claude-dev-env 1.95.0 → 2.0.1

package/_shared/pr-loop/scripts/code_rules_gate_parts/CLAUDE.md

@@ -0,0 +1,32 @@
+# code_rules_gate_parts
+
+The modules `code_rules_gate.py` wires together to run the code-rules gate. Each
+module owns one concern; the entry script imports them and re-exports their
+surface for the test suite.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `enforcer_loading.py` | Locates and loads `code_rules_enforcer.validate_content` from disk with the hooks directory on `sys.path` |
+| `git_file_sets.py` | Resolves the diff, staged, and untracked file sets from git, plus prefix filtering and staged line-span helpers |
+| `git_blob_readers.py` | Reads the committed and staged content of one file, and probes staged-index presence |
+| `added_line_maps.py` | Maps each changed file to the line numbers the current diff added, resolving renames and new files |
+| `violation_scoping.py` | Recovers a violation's line span from the enforcer message and partitions violations into blocking versus advisory |
+| `wrapper_plumb_check.py` | Flags a public wrapper that drops a same-file delegate's optional keyword arguments; holds the code-path and test-path classifiers |
+| `gate_running.py` | Validates the eligible file set, reports the inspected-file count, and prints the partitioned violation report |
+| `staged_test_running.py` | Runs the staged Python test files, grouped by their owning pytest config, in command-line-length-safe batches |
+| `gate_arguments.py` | Parses the gate's command-line arguments |
+| `__init__.py` | Package marker |
+
+## Subdirectory
+
+| Entry | Description |
+|---|---|
+| `tests/` | pytest suite with one test module per module above |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/_shared/pr-loop/scripts/code_rules_gate_parts/tests/
+```

package/_shared/pr-loop/scripts/code_rules_gate_parts/__init__.py

@@ -0,0 +1,7 @@
+"""Decomposed modules that make up the code-rules gate entry point.
+
+Each module owns one concern of the gate: enforcer loading, git file-set
+resolution, added-line maps, violation scoping, wrapper plumb-through
+detection, gate execution, and staged-test running. The ``code_rules_gate``
+entry module in the parent directory wires them together.
+"""

package/_shared/pr-loop/scripts/code_rules_gate_parts/added_line_maps.py

@@ -0,0 +1,268 @@
+"""Map each changed file to the line numbers the current diff added.
+
+The gate scopes a violation by whether its span meets an added line, so it needs
+the added-line set per file. This module resolves that set for an ordinary
+change, a brand-new file (its whole line span), and a rename (only the lines new
+relative to the source blob).
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+from pr_loop_shared_constants.code_rules_gate_constants import (
+    EXPECTED_NON_RENAME_COLUMN_COUNT,
+    EXPECTED_RENAME_COLUMN_COUNT,
+    GIT_NAME_STATUS_RENAMED_PREFIX,
+)
+from terminology_sweep import repository_environment
+
+from code_rules_gate_parts.git_file_sets import (
+    _git_bytes_or_exit,
+    _git_text_or_exit,
+    resolve_merge_base,
+)
+from code_rules_gate_parts.violation_scoping import parse_added_line_numbers
+
+
+def _run_git_text_capture(
+    repository_root: Path, all_git_arguments: list[str]
+) -> subprocess.CompletedProcess[str]:
+    """Run a git command in text mode and return the completed process."""
+    return subprocess.run(
+        all_git_arguments,
+        cwd=str(repository_root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+        env=repository_environment(),
+    )
+
+
+def is_file_new_at_base(repository_root: Path, merge_base: str, relative_path_posix: str) -> bool:
+    """Check whether *relative_path_posix* did not exist at *merge_base*.
+
+    Args:
+        repository_root: Repository root used as the ``git -C`` target.
+        merge_base: The merge-base SHA against which to check existence.
+        relative_path_posix: Repository-relative POSIX path to inspect.
+
+    Returns:
+        True when the blob is absent at the merge base (added on the HEAD side).
+    """
+    completed = _run_git_text_capture(
+        repository_root,
+        ["git", "cat-file", "-e", f"{merge_base}:{relative_path_posix}"],
+    )
+    return completed.returncode != 0
+
+
+def added_lines_for_file(
+    repository_root: Path, merge_base: str, relative_path_posix: str
+) -> set[int]:
+    """Return added line numbers for *relative_path_posix* since *merge_base*.
+
+    Args:
+        repository_root: Repository root used as the ``git -C`` target.
+        merge_base: The merge-base SHA against which to diff.
+        relative_path_posix: Repository-relative POSIX path to inspect.
+
+    Returns:
+        The line numbers added on the HEAD side of the diff.
+
+    Raises:
+        SystemExit: When the diff command returns non-zero.
+    """
+    diff_text = _git_text_or_exit(
+        repository_root,
+        ["git", "diff", "--unified=0", f"{merge_base}..HEAD", "--", relative_path_posix],
+        f"code_rules_gate: git diff --unified=0 failed for {relative_path_posix}",
+    )
+    if not diff_text.strip():
+        return set()
+    return parse_added_line_numbers(diff_text)
+
+
+def whole_file_line_set(file_path: Path) -> set[int]:
+    """Return the set of line numbers covering an entire file.
+
+    Args:
+        file_path: Path to the file whose line span is summarized.
+
+    Returns:
+        Every line number in *file_path*, or an empty set when it is unreadable
+        or empty.
+    """
+    try:
+        total_lines = len(file_path.read_text(encoding="utf-8").splitlines())
+    except (OSError, UnicodeDecodeError) as read_error:
+        sys.stderr.write(f"code_rules_gate: skipping unreadable file {file_path}: {read_error}\n")
+        return set()
+    if total_lines <= 0:
+        return set()
+    return set(range(1, total_lines + 1))
+
+
+def _rename_pairs_from_tokens(all_tokens: list[str]) -> dict[str, str]:
+    """Walk null-separated name-status tokens into destination-to-source pairs.
+
+    Args:
+        all_tokens: The decoded name-status tokens, in stream order.
+
+    Returns:
+        A mapping from rename-destination path to rename-source path.
+    """
+    rename_source_by_destination: dict[str, str] = {}
+    next_token_index = 0
+    while next_token_index < len(all_tokens):
+        status_code = all_tokens[next_token_index]
+        if not status_code.startswith(GIT_NAME_STATUS_RENAMED_PREFIX):
+            next_token_index += EXPECTED_NON_RENAME_COLUMN_COUNT
+            continue
+        if next_token_index + EXPECTED_RENAME_COLUMN_COUNT > len(all_tokens):
+            break
+        rename_slice = all_tokens[
+            next_token_index + 1 : next_token_index + EXPECTED_RENAME_COLUMN_COUNT
+        ]
+        destination_path = rename_slice[1].replace("\\", "/")
+        rename_source_by_destination[destination_path] = rename_slice[0].replace("\\", "/")
+        next_token_index += EXPECTED_RENAME_COLUMN_COUNT
+    return rename_source_by_destination
+
+
+def renamed_file_source_map_since(repository_root: Path, merge_base: str) -> dict[str, str]:
+    """Return a mapping from rename-destination path to rename-source path.
+
+    ::
+
+        ok: a path holding a tab byte round-trips through the -z stream unmangled
+
+    Args:
+        repository_root: Repository root used as the ``git -C`` target.
+        merge_base: The merge-base SHA against which to diff.
+
+    Returns:
+        A mapping from rename-destination POSIX path to rename-source path.
+
+    Raises:
+        SystemExit: When ``git diff --name-status`` returns non-zero.
+    """
+    raw_stdout = _git_bytes_or_exit(
+        repository_root,
+        ["git", "diff", "--name-status", "-M", "-z", f"{merge_base}..HEAD"],
+        "code_rules_gate: git diff --name-status -M -z failed",
+    )
+    all_tokens = [
+        each_token.decode("utf-8", errors="replace")
+        for each_token in raw_stdout.split(b"\x00")
+        if each_token
+    ]
+    return _rename_pairs_from_tokens(all_tokens)
+
+
+def added_lines_for_renamed_file(
+    repository_root: Path,
+    merge_base: str,
+    source_posix: str,
+    destination_posix: str,
+) -> set[int]:
+    """Return added line numbers for a renamed file via blob comparison.
+
+    Args:
+        repository_root: Repository root used as the ``git -C`` target.
+        merge_base: The merge-base SHA against which to compare blobs.
+        source_posix: Rename-source POSIX path at the merge base.
+        destination_posix: Rename-destination POSIX path at HEAD.
+
+    Returns:
+        The line numbers added on the HEAD side; empty on diff failure.
+    """
+    source_reference = f"{merge_base}:{source_posix}"
+    destination_reference = f"HEAD:{destination_posix}"
+    completed = _run_git_text_capture(
+        repository_root,
+        ["git", "diff", "--unified=0", source_reference, destination_reference],
+    )
+    if completed.returncode != 0:
+        sys.stderr.write(f"code_rules_gate: rename diff failed: {completed.stderr.strip()}\n")
+        return set()
+    if not completed.stdout.strip():
+        return set()
+    return parse_added_line_numbers(completed.stdout)
+
+
+def _resolved_under_root(each_path: Path, resolved_root: Path) -> Path | None:
+    """Return *each_path* resolved when it sits under *resolved_root*, else None."""
+    try:
+        resolved = each_path.resolve()
+    except OSError:
+        return None
+    try:
+        resolved.relative_to(resolved_root)
+    except ValueError:
+        return None
+    return resolved
+
+
+def _added_lines_for_one_path(
+    resolved_root: Path,
+    merge_base: str,
+    all_rename_sources: dict[str, str],
+    resolved: Path,
+) -> set[int]:
+    """Resolve added lines for one path, honoring renames and new files.
+
+    Args:
+        resolved_root: The resolved repository root.
+        merge_base: The merge-base SHA against which to diff.
+        all_rename_sources: Destination-to-source rename map for the range.
+        resolved: The resolved absolute path to inspect.
+
+    Returns:
+        The added line numbers for the path.
+    """
+    relative_posix = str(resolved.relative_to(resolved_root)).replace("\\", "/")
+    if relative_posix in all_rename_sources:
+        return added_lines_for_renamed_file(
+            resolved_root, merge_base, all_rename_sources[relative_posix], relative_posix
+        )
+    added_numbers = added_lines_for_file(resolved_root, merge_base, relative_posix)
+    if (
+        not added_numbers
+        and resolved.is_file()
+        and is_file_new_at_base(resolved_root, merge_base, relative_posix)
+    ):
+        return whole_file_line_set(resolved)
+    return added_numbers
+
+
+def added_lines_by_file(
+    repository_root: Path,
+    base_reference: str,
+    all_file_paths: list[Path],
+) -> dict[Path, set[int]]:
+    """Build a per-file map of added line numbers across the branch.
+
+    Args:
+        repository_root: Repository root for diff invocations.
+        base_reference: The git reference to merge-base against.
+        all_file_paths: File paths whose added lines are collected.
+
+    Returns:
+        A mapping from resolved file path to its added line numbers, with
+        renames resolved against the original source path.
+    """
+    merge_base = resolve_merge_base(repository_root, base_reference)
+    resolved_root = repository_root.resolve()
+    all_rename_sources = renamed_file_source_map_since(resolved_root, merge_base)
+    added_by_path: dict[Path, set[int]] = {}
+    for each_path in all_file_paths:
+        resolved = _resolved_under_root(each_path, resolved_root)
+        if resolved is None:
+            continue
+        added_by_path[resolved] = _added_lines_for_one_path(
+            resolved_root, merge_base, all_rename_sources, resolved
+        )
+    return added_by_path

package/_shared/pr-loop/scripts/code_rules_gate_parts/enforcer_loading.py

@@ -0,0 +1,172 @@
+"""Load the code-rules enforcer's ``validate_content`` for in-process use.
+
+The gate runs the same ``validate_content`` the PreToolUse enforcer runs, so it
+locates the ``hooks/blocking/code_rules_enforcer.py`` module from disk, executes
+it with the hooks directory on ``sys.path``, and hands back its callable.
+"""
+
+import importlib.machinery
+import importlib.util
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from types import ModuleType
+
+from pr_loop_shared_constants.code_rules_gate_constants import GATE_ERROR_EXIT_CODE
+
+ValidateContentCallable = Callable[..., list[str]]
+
+_ENFORCER_RELATIVE_PATH = Path("hooks") / "blocking" / "code_rules_enforcer.py"
+
+
+def _first_ancestor_with_enforcer(starting_form: Path) -> Path | None:
+    """Return the first ancestor of *starting_form* that holds the enforcer.
+
+    Args:
+        starting_form: A resolved or absolute path to climb from.
+
+    Returns:
+        The ancestor directory containing the enforcer file, or None.
+    """
+    for each_candidate in [starting_form, *starting_form.parents]:
+        if (each_candidate / _ENFORCER_RELATIVE_PATH).is_file():
+            return each_candidate
+    return None
+
+
+def resolve_claude_dev_env_root(starting_path: Path) -> Path:
+    """Walk up from *starting_path* to the claude-dev-env package root.
+
+    Args:
+        starting_path: A path inside the worktree; the function climbs to the
+            ancestor holding ``hooks/blocking/code_rules_enforcer.py``.
+
+    Returns:
+        The resolved package root that contains the enforcer file.
+
+    Raises:
+        SystemExit: When no ancestor contains the enforcer.
+    """
+    starting = Path(starting_path).resolve()
+    found_root = _first_ancestor_with_enforcer(starting)
+    if found_root is not None:
+        return found_root
+    sys.stderr.write(
+        f"code_rules_gate: could not locate {_ENFORCER_RELATIVE_PATH} above {starting}\n"
+    )
+    raise SystemExit(GATE_ERROR_EXIT_CODE)
+
+
+def _resolve_package_root_absolute(starting_path: Path) -> Path:
+    """Return the enforcer-bearing root from an absolute or resolved form.
+
+    Args:
+        starting_path: The path to climb from, tried both absolute and resolved.
+
+    Returns:
+        The ancestor directory containing the enforcer file.
+
+    Raises:
+        SystemExit: When neither form finds the enforcer.
+    """
+    for each_starting_form in (
+        Path(starting_path).absolute(),
+        Path(starting_path).resolve(),
+    ):
+        found_root = _first_ancestor_with_enforcer(each_starting_form)
+        if found_root is not None:
+            return found_root
+    raise SystemExit(GATE_ERROR_EXIT_CODE)
+
+
+def _hooks_constants_module_names() -> list[str]:
+    """Return the loaded module names that belong to the hooks constants package."""
+    return [
+        each_key
+        for each_key in list(sys.modules)
+        if each_key == "hooks_constants" or each_key.startswith("hooks_constants.")
+    ]
+
+
+def _load_enforcer_specification(
+    enforcer_path: Path,
+) -> importlib.machinery.ModuleSpec:
+    """Return an import spec for the enforcer module at *enforcer_path*.
+
+    Args:
+        enforcer_path: The on-disk path of ``code_rules_enforcer.py``.
+
+    Returns:
+        A loadable module specification for the enforcer.
+
+    Raises:
+        SystemExit: When the file is missing or a spec cannot be built.
+    """
+    if not enforcer_path.is_file():
+        sys.stderr.write(f"code_rules_gate: missing enforcer at {enforcer_path}\n")
+        raise SystemExit(GATE_ERROR_EXIT_CODE)
+    specification = importlib.util.spec_from_file_location("code_rules_enforcer", enforcer_path)
+    if specification is None or specification.loader is None:
+        sys.stderr.write("code_rules_gate: could not load code_rules_enforcer.\n")
+        raise SystemExit(GATE_ERROR_EXIT_CODE)
+    return specification
+
+
+def _exec_enforcer_with_hooks_on_path(
+    specification: importlib.machinery.ModuleSpec, module: ModuleType
+) -> None:
+    """Execute *module* with the hooks directory temporarily on ``sys.path``.
+
+    Args:
+        specification: The loadable spec whose loader executes the module.
+        module: The freshly created enforcer module object to populate.
+    """
+    loader = specification.loader
+    assert loader is not None
+    package_root_for_imports = _resolve_package_root_absolute(Path(__file__).absolute())
+    hooks_root_path = str(package_root_for_imports / "hooks")
+    while hooks_root_path in sys.path:
+        sys.path.remove(hooks_root_path)
+    if hooks_root_path not in sys.path:
+        sys.path.insert(0, hooks_root_path)
+    all_saved_modules: dict[str, ModuleType] = {
+        each_name: sys.modules.pop(each_name) for each_name in _hooks_constants_module_names()
+    }
+    try:
+        loader.exec_module(module)
+    finally:
+        _restore_hooks_constants_modules(all_saved_modules, hooks_root_path)
+
+
+def load_validate_content() -> ValidateContentCallable:
+    """Load ``code_rules_enforcer.validate_content`` for in-process use.
+
+    Returns:
+        The ``validate_content`` callable from the enforcer module.
+
+    Raises:
+        SystemExit: When the package root or the enforcer module cannot load.
+    """
+    package_root = resolve_claude_dev_env_root(Path(__file__).resolve())
+    specification = _load_enforcer_specification(
+        package_root / "hooks" / "blocking" / "code_rules_enforcer.py"
+    )
+    module = importlib.util.module_from_spec(specification)
+    _exec_enforcer_with_hooks_on_path(specification, module)
+    return module.validate_content
+
+
+def _restore_hooks_constants_modules(
+    all_saved_modules: dict[str, ModuleType], hooks_root_path: str
+) -> None:
+    """Restore the sys.path and hooks-constants state after loading the enforcer.
+
+    Args:
+        all_saved_modules: The hooks-constants modules captured before loading.
+        hooks_root_path: The hooks directory added to sys.path for the load.
+    """
+    while hooks_root_path in sys.path:
+        sys.path.remove(hooks_root_path)
+    for each_name in _hooks_constants_module_names():
+        sys.modules.pop(each_name, None)
+    sys.modules.update(all_saved_modules)

package/_shared/pr-loop/scripts/code_rules_gate_parts/gate_arguments.py

@@ -0,0 +1,70 @@
+"""Parse the command-line arguments for the code-rules gate."""
+
+import argparse
+from pathlib import Path
+
+
+def _add_source_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add the repo-root, base-ref, and staged-mode arguments to *parser*."""
+    parser.add_argument(
+        "--repo-root",
+        type=Path,
+        default=None,
+        help="Repository root (default: cwd).",
+    )
+    parser.add_argument(
+        "--base",
+        default="origin/main",
+        help="Merge-base ref for git diff (default: origin/main).",
+    )
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        default=False,
+        help="Scope to staged changes only (git diff --cached).",
+    )
+
+
+def _add_filter_arguments(parser: argparse.ArgumentParser) -> None:
+    """Add the only-under filter and the explicit-paths arguments to *parser*."""
+    parser.add_argument(
+        "--only-under",
+        action="append",
+        default=[],
+        dest="only_under",
+        metavar="PREFIX",
+        help="Keep only files whose repo-relative POSIX path starts with or "
+        "equals PREFIX (repeatable).",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        type=Path,
+        help="Optional explicit files; if set, git diff is not used.",
+    )
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    """Return the argument parser with every gate option registered."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Run the code-rules validators on files in the working tree. Default "
+            "file set: git diff since the merge-base joined with untracked files."
+        ),
+    )
+    _add_source_arguments(parser)
+    _add_filter_arguments(parser)
+    return parser
+
+
+def parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
+    """Parse the command-line arguments for the code-rules gate.
+
+    Args:
+        all_arguments: Command-line argument list forwarded to argparse.
+
+    Returns:
+        The parsed namespace with ``repo_root``, ``base``, ``staged``,
+        ``only_under``, and ``paths`` attributes.
+    """
+    return _build_argument_parser().parse_args(all_arguments)