claude-dev-env 2.8.0 → 2.10.0

package/skills/split-pr/scripts/split_pr_git_operations.py

@@ -0,0 +1,184 @@
+"""Materialize verified split slices as local Git commits with restore safety.
+
+::
+
+    outcome = materialize_slice_commit(
+        repository_path=repo,
+        all_slice_paths=["a.py"],
+        commit_message="chore: config slice",
+        expected_base_sha=head_before,
+        run=run_process,
+    )
+    # on failure, repository returns to expected_base_sha with clean tree
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from config.git_operations_constants import (
+    ALL_GIT_CLEAN_FORCE_DIR,
+    ALL_GIT_RESTORE_STAGED_WORKTREE,
+    ALL_GIT_REV_PARSE_HEAD,
+    ALL_GIT_STATUS_PORCELAIN,
+    ERROR_ADD_FAILED,
+    ERROR_BASE_MISMATCH_TEMPLATE,
+    ERROR_CHECKOUT_FAILED,
+    ERROR_CLEAN_FAILED,
+    ERROR_COMMIT_FAILED,
+    ERROR_DIRTY_TREE,
+    ERROR_EMPTY_SLICE_PATHS,
+    ERROR_RESTORE_FAILED,
+    ERROR_REV_PARSE_FAILED,
+    ERROR_STATUS_FAILED,
+    GIT_ADD,
+    GIT_CHECKOUT,
+    GIT_COMMAND,
+    GIT_COMMIT,
+    GIT_COMMIT_MESSAGE_FLAG,
+    GIT_FORCE_FLAG,
+    GIT_PATHSPEC_SEPARATOR,
+    RECORD_KEY_ALL_PATHS,
+    RECORD_KEY_BASE_SHA,
+    RECORD_KEY_COMMIT_SHA,
+    RECORD_KEY_EXIT_CODE,
+)
+from config.plan_constants import EXIT_CODE_SUCCESS
+from split_pr_process_runner import CapturedProcessOutcome, ProcessRunner, run_process
+from split_pr_script_types import JsonObject
+
+
+def _git(
+    run: ProcessRunner,
+    repository_path: Path,
+    all_git_args: list[str],
+) -> CapturedProcessOutcome:
+    return run([GIT_COMMAND, *all_git_args], str(repository_path))
+
+
+def read_head_sha(repository_path: Path, run: ProcessRunner = run_process) -> str:
+    """Return the current HEAD commit SHA.
+
+    Args:
+        repository_path: Git repository root.
+        run: Process runner (injectable for tests).
+
+    Returns:
+        Stripped HEAD sha text.
+
+    Raises:
+        RuntimeError: When rev-parse fails.
+    """
+    outcome = _git(run, repository_path, list(ALL_GIT_REV_PARSE_HEAD))
+    if not outcome.is_success:
+        raise RuntimeError(outcome.stderr_text or ERROR_REV_PARSE_FAILED)
+    return outcome.stdout_text.strip()
+
+
+def assert_clean_worktree(
+    repository_path: Path,
+    run: ProcessRunner = run_process,
+) -> None:
+    """Refuse materialization when the worktree is dirty.
+
+    Args:
+        repository_path: Git repository root.
+        run: Process runner.
+
+    Raises:
+        RuntimeError: When porcelain status is non-empty or the command fails.
+    """
+    outcome = _git(run, repository_path, list(ALL_GIT_STATUS_PORCELAIN))
+    if not outcome.is_success:
+        raise RuntimeError(outcome.stderr_text or ERROR_STATUS_FAILED)
+    if outcome.stdout_text.strip():
+        raise RuntimeError(ERROR_DIRTY_TREE)
+
+
+def restore_repository_state(
+    repository_path: Path,
+    target_sha: str,
+    run: ProcessRunner = run_process,
+) -> None:
+    """Checkout target_sha and discard uncommitted changes.
+
+    Args:
+        repository_path: Git repository root.
+        target_sha: Commit to restore.
+        run: Process runner.
+
+    Raises:
+        RuntimeError: When checkout or clean fails.
+    """
+    checkout = _git(
+        run, repository_path, [GIT_CHECKOUT, GIT_FORCE_FLAG, target_sha]
+    )
+    if not checkout.is_success:
+        raise RuntimeError(checkout.stderr_text or ERROR_CHECKOUT_FAILED)
+    restore = _git(run, repository_path, list(ALL_GIT_RESTORE_STAGED_WORKTREE))
+    if not restore.is_success:
+        raise RuntimeError(restore.stderr_text or ERROR_RESTORE_FAILED)
+    clean = _git(run, repository_path, list(ALL_GIT_CLEAN_FORCE_DIR))
+    if not clean.is_success:
+        raise RuntimeError(clean.stderr_text or ERROR_CLEAN_FAILED)
+
+
+def materialize_slice_commit(
+    repository_path: Path,
+    all_slice_paths: list[str],
+    commit_message: str,
+    expected_base_sha: str,
+    run: ProcessRunner = run_process,
+) -> JsonObject:
+    """Stage only slice paths and create one commit from a verified base.
+
+    Args:
+        repository_path: Git repository root.
+        all_slice_paths: Paths relative to the repository for this slice only.
+        commit_message: Conventional commit message (already normalized).
+        expected_base_sha: HEAD must equal this before staging.
+        run: Process runner.
+
+    Returns:
+        Map with keys commit_sha, base_sha, all_paths.
+
+    Raises:
+        RuntimeError: On dirty tree, base mismatch, add/commit failure, or
+            when restore after failure also fails.
+    """
+    assert_clean_worktree(repository_path, run)
+    head_sha = read_head_sha(repository_path, run)
+    if head_sha != expected_base_sha:
+        raise RuntimeError(
+            ERROR_BASE_MISMATCH_TEMPLATE.format(
+                head_sha=head_sha,
+                expected_base_sha=expected_base_sha,
+            )
+        )
+    if not all_slice_paths:
+        raise RuntimeError(ERROR_EMPTY_SLICE_PATHS)
+    try:
+        add_outcome = _git(
+            run,
+            repository_path,
+            [GIT_ADD, GIT_PATHSPEC_SEPARATOR, *all_slice_paths],
+        )
+        if not add_outcome.is_success:
+            raise RuntimeError(add_outcome.stderr_text or ERROR_ADD_FAILED)
+        commit_outcome = _git(
+            run,
+            repository_path,
+            [GIT_COMMIT, GIT_COMMIT_MESSAGE_FLAG, commit_message],
+        )
+        if not commit_outcome.is_success:
+            raise RuntimeError(commit_outcome.stderr_text or ERROR_COMMIT_FAILED)
+        new_sha = read_head_sha(repository_path, run)
+        return {
+            RECORD_KEY_COMMIT_SHA: new_sha,
+            RECORD_KEY_BASE_SHA: expected_base_sha,
+            RECORD_KEY_ALL_PATHS: list(all_slice_paths),
+            RECORD_KEY_EXIT_CODE: EXIT_CODE_SUCCESS,
+        }
+    except RuntimeError:
+        restore_repository_state(repository_path, expected_base_sha, run)
+        raise

package/skills/split-pr/scripts/split_pr_layer_order.py

@@ -0,0 +1,58 @@
+"""Deterministic layer order for split-plan slices.
+
+::
+
+    sort_slices_by_layer_order([{"layer": "docs"}, {"layer": "config"}])
+    # config first, then docs
+"""
+
+from __future__ import annotations
+
+from config.plan_constants import (
+    ALL_LAYER_RANK_BY_NAME,
+    DEFAULT_SLICE_LAYER,
+    SLICE_KEY_LAYER,
+    UNKNOWN_LAYER_RANK,
+)
+
+JsonObject = dict[str, object]
+
+
+def layer_rank(layer_name: str) -> int:
+    """Return the stable rank for a layer name (unknown layers sort last).
+
+    Args:
+        layer_name: Layer token such as ``config`` or ``tests``.
+
+    Returns:
+        Integer rank; lower values sort earlier.
+    """
+    return ALL_LAYER_RANK_BY_NAME.get(layer_name, UNKNOWN_LAYER_RANK)
+
+
+def sort_slices_by_layer_order(all_slices: list[JsonObject]) -> list[JsonObject]:
+    """Return a new list of slices sorted by layer rank then original index.
+
+    Args:
+        all_slices: Slice maps that may carry a ``layer`` key.
+
+    Returns:
+        Fresh list sorted stably by layer rank.
+    """
+    all_indexed_slices = list(enumerate(all_slices))
+
+    def _rank_for_sort(
+        all_indexed_slice: tuple[int, JsonObject],
+    ) -> tuple[int, int]:
+        each_index, each_slice = all_indexed_slice
+        layer_field = each_slice.get(SLICE_KEY_LAYER, DEFAULT_SLICE_LAYER)
+        if layer_field is None:
+            layer_name = DEFAULT_SLICE_LAYER
+        else:
+            layer_name = str(layer_field)
+        return (layer_rank(layer_name), each_index)
+
+    return [
+        each_slice
+        for _each_index, each_slice in sorted(all_indexed_slices, key=_rank_for_sort)
+    ]

package/skills/split-pr/scripts/split_pr_paginate.py

@@ -0,0 +1,119 @@
+"""Paginated PR changed-file intake at an exact source commit identity.
+
+Uses ``gh api --paginate --slurp`` so every page of the pulls files list is
+collected before filtering (cross-page sorts stay correct).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+from config.plan_constants import (
+    EXIT_CODE_SUCCESS,
+    FILE_KEY_ADDITIONS,
+    FILE_KEY_DELETIONS,
+    FILE_KEY_PATH,
+    FILE_KEY_SHA,
+    GH_API,
+    GH_COMMAND,
+    GH_PAGINATE_FLAG,
+    GH_PULLS_FILES_PATH_TEMPLATE,
+    GH_REST_FILE_FILENAME,
+    GH_SLURP_FLAG,
+    UTF8_ENCODING,
+)
+
+JsonObject = dict[str, object]
+
+
+def fetch_all_pr_changed_files(
+    owner: str,
+    repo: str,
+    pr_number: int,
+) -> list[JsonObject]:
+    """Fetch every changed file across all pages for a pull request.
+
+    Args:
+        owner: Repository owner.
+        repo: Repository name.
+        pr_number: Pull request number.
+
+    Returns:
+        List of path/additions/deletions/sha maps.
+
+    Raises:
+        RuntimeError: When the gh API call fails.
+        json.JSONDecodeError: When the response is not JSON.
+    """
+    api_path = GH_PULLS_FILES_PATH_TEMPLATE.format(
+        owner=owner,
+        repo=repo,
+        pr_number=pr_number,
+    )
+    all_command = [
+        GH_COMMAND,
+        GH_API,
+        api_path,
+        GH_PAGINATE_FLAG,
+        GH_SLURP_FLAG,
+    ]
+    completed = subprocess.run(
+        all_command,
+        capture_output=True,
+        text=True,
+        check=False,
+        encoding=UTF8_ENCODING,
+    )
+    if completed.returncode != EXIT_CODE_SUCCESS:
+        raise RuntimeError(completed.stderr.strip() or "gh api pulls files failed")
+    return parse_paginated_files_payload(completed.stdout)
+
+
+def parse_paginated_files_payload(raw_json: str) -> list[JsonObject]:
+    """Flatten a --slurp JSON array-of-pages into file records.
+
+    Args:
+        raw_json: stdout from ``gh api --paginate --slurp``.
+
+    Returns:
+        Deduplicated file records in first-seen order.
+
+    Raises:
+        ValueError: When the JSON root is not an array of pages or files.
+        json.JSONDecodeError: When raw_json is not valid JSON.
+    """
+    loaded = json.loads(raw_json)
+    all_pages: list[object]
+    if isinstance(loaded, list) and loaded and isinstance(loaded[0], list):
+        all_pages = loaded
+    elif isinstance(loaded, list):
+        all_pages = [loaded]
+    else:
+        raise ValueError("paginated payload must be a JSON array")
+    all_file_records: list[JsonObject] = []
+    all_seen_paths: set[str] = set()
+    for each_page in all_pages:
+        if not isinstance(each_page, list):
+            continue
+        for each_file in each_page:
+            if not isinstance(each_file, dict):
+                continue
+            path = each_file.get(GH_REST_FILE_FILENAME)
+            if path is None:
+                path = each_file.get(FILE_KEY_PATH)
+            if not path:
+                continue
+            path_text = str(path)
+            if path_text in all_seen_paths:
+                continue
+            all_seen_paths.add(path_text)
+            all_file_records.append(
+                {
+                    FILE_KEY_PATH: path_text,
+                    FILE_KEY_ADDITIONS: int(each_file.get(FILE_KEY_ADDITIONS, 0) or 0),
+                    FILE_KEY_DELETIONS: int(each_file.get(FILE_KEY_DELETIONS, 0) or 0),
+                    FILE_KEY_SHA: str(each_file.get(FILE_KEY_SHA, "") or ""),
+                }
+            )
+    return all_file_records

package/skills/split-pr/scripts/split_pr_process_runner.py

@@ -0,0 +1,52 @@
+"""Run subprocess commands with captured text output for Git materialization."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from config.plan_constants import EXIT_CODE_SUCCESS, UTF8_ENCODING
+
+ProcessRunner = Callable[[list[str], str], "CapturedProcessOutcome"]
+
+
+@dataclass(frozen=True)
+class CapturedProcessOutcome:
+    """Captured outcome of one subprocess invocation."""
+
+    exit_code: int
+    stdout_text: str
+    stderr_text: str
+
+    @property
+    def is_success(self) -> bool:
+        return self.exit_code == EXIT_CODE_SUCCESS
+
+
+def run_process(
+    all_command: list[str],
+    working_directory: str,
+) -> CapturedProcessOutcome:
+    """Run a command and return exit code plus captured stdout/stderr text.
+
+    Args:
+        all_command: argv list (no shell).
+        working_directory: Directory the child process runs in.
+
+    Returns:
+        CapturedProcessOutcome with exit_code and text streams.
+    """
+    completed = subprocess.run(
+        all_command,
+        cwd=working_directory,
+        capture_output=True,
+        text=True,
+        check=False,
+        encoding=UTF8_ENCODING,
+    )
+    return CapturedProcessOutcome(
+        exit_code=completed.returncode,
+        stdout_text=completed.stdout or "",
+        stderr_text=completed.stderr or "",
+    )

package/skills/split-pr/scripts/split_pr_script_types.py

@@ -0,0 +1,126 @@
+"""Canonical split-plan records and validation.
+
+::
+
+    plan = build_split_plan(
+        source_commit="abc123",
+        all_changed_paths=["a.py", "b.py"],
+        all_slices=[{"id": "01-config", "title": "feat: cfg", "layer": "config", "all_paths": ["a.py"]}],
+    )
+    validate_split_plan(plan)  # raises ValueError when a path is unassigned
+"""
+
+from __future__ import annotations
+
+from config.plan_constants import (
+    DEFAULT_SLICE_LAYER,
+    PLAN_KEY_ALL_CHANGED_PATHS,
+    PLAN_KEY_ALL_SLICES,
+    PLAN_KEY_SCHEMA_VERSION,
+    PLAN_KEY_SOURCE_COMMIT,
+    PLAN_SCHEMA_VERSION,
+    SLICE_KEY_ALL_PATHS,
+    SLICE_KEY_ID,
+    SLICE_KEY_LAYER,
+    SLICE_KEY_TITLE,
+    TITLE_PREFIX_SEPARATOR,
+)
+from split_pr_layer_order import sort_slices_by_layer_order
+from split_pr_title import normalize_split_title
+
+JsonObject = dict[str, object]
+
+
+def build_split_plan(
+    source_commit: str,
+    all_changed_paths: list[str],
+    all_slices: list[JsonObject],
+) -> JsonObject:
+    """Build a schema-versioned split plan with normalized titles and layer order.
+
+    Args:
+        source_commit: Exact commit SHA the file list was taken from.
+        all_changed_paths: Full path set for the source commit.
+        all_slices: Slice maps with id, title, layer, and path lists.
+
+    Returns:
+        Plan document ready for validate_split_plan.
+    """
+    all_normalized_slices: list[JsonObject] = []
+    for each_slice in all_slices:
+        title = normalize_split_title(str(each_slice.get(SLICE_KEY_TITLE, "")))
+        all_paths = each_slice.get(SLICE_KEY_ALL_PATHS, [])
+        if not isinstance(all_paths, list):
+            all_paths = []
+        all_normalized_slices.append(
+            {
+                SLICE_KEY_ID: str(each_slice.get(SLICE_KEY_ID, "")),
+                SLICE_KEY_TITLE: title,
+                SLICE_KEY_LAYER: str(
+                    each_slice.get(SLICE_KEY_LAYER, DEFAULT_SLICE_LAYER)
+                ),
+                SLICE_KEY_ALL_PATHS: [str(each_path) for each_path in all_paths],
+            }
+        )
+    all_ordered = sort_slices_by_layer_order(all_normalized_slices)
+    return {
+        PLAN_KEY_SCHEMA_VERSION: PLAN_SCHEMA_VERSION,
+        PLAN_KEY_SOURCE_COMMIT: source_commit,
+        PLAN_KEY_ALL_CHANGED_PATHS: list(all_changed_paths),
+        PLAN_KEY_ALL_SLICES: all_ordered,
+    }
+
+
+def validate_split_plan(all_plan: JsonObject) -> None:
+    """Require every changed path is assigned to exactly one slice.
+
+    Args:
+        all_plan: Plan document from build_split_plan.
+
+    Raises:
+        ValueError: When schema, assignment, or title contracts fail.
+    """
+    if all_plan.get(PLAN_KEY_SCHEMA_VERSION) != PLAN_SCHEMA_VERSION:
+        raise ValueError(
+            f"schema_version must be {PLAN_SCHEMA_VERSION}, "
+            f"got {all_plan.get(PLAN_KEY_SCHEMA_VERSION)!r}"
+        )
+    source_commit = all_plan.get(PLAN_KEY_SOURCE_COMMIT)
+    if not isinstance(source_commit, str) or not source_commit.strip():
+        raise ValueError("source_commit must be a non-empty string")
+    all_changed = all_plan.get(PLAN_KEY_ALL_CHANGED_PATHS)
+    if not isinstance(all_changed, list):
+        raise ValueError("all_changed_paths must be a list")
+    all_slices = all_plan.get(PLAN_KEY_ALL_SLICES)
+    if not isinstance(all_slices, list) or not all_slices:
+        raise ValueError("all_slices must be a non-empty list")
+    all_assigned: list[str] = []
+    for each_slice in all_slices:
+        if not isinstance(each_slice, dict):
+            raise ValueError("each slice must be an object")
+        slice_id = each_slice.get(SLICE_KEY_ID)
+        if not isinstance(slice_id, str) or not slice_id.strip():
+            raise ValueError(f"slice id must be a non-empty string: {slice_id!r}")
+        title = each_slice.get(SLICE_KEY_TITLE)
+        if not isinstance(title, str) or TITLE_PREFIX_SEPARATOR not in title:
+            raise ValueError(f"slice title missing conventional prefix: {title!r}")
+        normalized = normalize_split_title(title)
+        if normalized != title:
+            raise ValueError(
+                f"slice title is not normalized: {title!r} != {normalized!r}"
+            )
+        all_paths = each_slice.get(SLICE_KEY_ALL_PATHS)
+        if not isinstance(all_paths, list):
+            raise ValueError("slice all_paths must be a list")
+        for each_path in all_paths:
+            all_assigned.append(str(each_path))
+    all_changed_set = {str(each_path) for each_path in all_changed}
+    all_assigned_set = set(all_assigned)
+    if all_assigned_set != all_changed_set:
+        missing = sorted(all_changed_set - all_assigned_set)
+        extra = sorted(all_assigned_set - all_changed_set)
+        raise ValueError(
+            f"path assignment mismatch missing={missing!r} extra={extra!r}"
+        )
+    if len(all_assigned) != len(all_assigned_set):
+        raise ValueError("a path is assigned to more than one slice")

package/skills/split-pr/scripts/split_pr_title.py

@@ -0,0 +1,41 @@
+"""Normalize split-PR titles to exactly one conventional commit prefix.
+
+::
+
+    normalize_split_title("feat: foo") -> "feat: foo"
+    normalize_split_title("feat: feat: foo") -> "feat: foo"
+    normalize_split_title("bare title") -> "chore: bare title"
+"""
+
+from __future__ import annotations
+
+import re
+
+from config.plan_constants import (
+    CONVENTIONAL_PREFIX_PATTERN,
+    DEFAULT_EMPTY_TITLE_REMAINDER,
+    DEFAULT_TITLE_PREFIX,
+    TITLE_PREFIX_SEPARATOR,
+)
+
+def normalize_split_title(raw_title: str) -> str:
+    """Return a title with exactly one conventional-commit prefix.
+
+    Args:
+        raw_title: Candidate title that may lack a prefix or stack several.
+
+    Returns:
+        Title of the form ``<prefix>: <remainder>`` with one prefix only.
+    """
+    prefix_pattern = re.compile(CONVENTIONAL_PREFIX_PATTERN, re.IGNORECASE)
+    remainder = raw_title.strip()
+    chosen_prefix = DEFAULT_TITLE_PREFIX
+    while True:
+        match = prefix_pattern.match(remainder)
+        if match is None:
+            break
+        chosen_prefix = match.group("prefix").lower()
+        remainder = remainder[match.end() :].lstrip()
+    if not remainder:
+        remainder = DEFAULT_EMPTY_TITLE_REMAINDER
+    return f"{chosen_prefix}{TITLE_PREFIX_SEPARATOR}{remainder}"