claude-dev-env 2.8.0 → 2.10.0

package/skills/split-pr/scripts/config/packing_constants.py

@@ -0,0 +1,61 @@
+"""Constants for review-budget packing of categorized files."""
+
+from __future__ import annotations
+
+from config.plan_constants import ALL_LAYER_ORDER
+from config.split_pr_constants import (
+    DEFAULT_SPLIT_HAND_WRITTEN_LINE_THRESHOLD,
+    SPLIT_ANALYSIS_HAND_WRITTEN_LINE_THRESHOLD,
+)
+
+REVIEW_BUDGET_HAND_WRITTEN_LINES: int = SPLIT_ANALYSIS_HAND_WRITTEN_LINE_THRESHOLD
+HARD_CAP_HAND_WRITTEN_LINES: int = DEFAULT_SPLIT_HAND_WRITTEN_LINE_THRESHOLD
+SLICE_ID_TEMPLATE: str = "{index:02d}-{layer}"
+SLICE_TITLE_TEMPLATE: str = "chore: {layer} slice {index}"
+(
+    LAYER_CONFIG,
+    LAYER_BACKEND,
+    LAYER_FRONTEND,
+    LAYER_TESTS,
+    LAYER_DOCS,
+    LAYER_OTHER,
+) = ALL_LAYER_ORDER
+ALL_TEST_PATH_MARKERS: tuple[str, ...] = (
+    "/tests/",
+    "/test/",
+    "test_",
+    "_test.",
+    ".test.",
+    ".spec.",
+)
+ALL_DOC_SUFFIXES: tuple[str, ...] = (".md", ".rst", ".txt")
+ALL_CONFIG_BASENAMES: frozenset[str] = frozenset(
+    {
+        "package.json",
+        "pyproject.toml",
+        "setup.cfg",
+        "tsconfig.json",
+        ".eslintrc",
+        "ruff.toml",
+    }
+)
+ALL_CONFIG_PATH_MARKERS: tuple[str, ...] = ("/config/", "/.github/")
+ALL_FRONTEND_SUFFIXES: tuple[str, ...] = (
+    ".tsx",
+    ".jsx",
+    ".css",
+    ".scss",
+    ".vue",
+    ".svelte",
+)
+ALL_BACKEND_SUFFIXES: tuple[str, ...] = (
+    ".py",
+    ".mjs",
+    ".js",
+    ".ts",
+    ".go",
+    ".rs",
+)
+EXCLUDED_CHURN_LAYER_LABEL: str = "excluded-churn"
+EMPTY_HAND_WRITTEN_TITLE: str = "chore: empty hand-written set"
+EMPTY_HAND_WRITTEN_SLICE_ID: str = "01-other"

package/skills/split-pr/scripts/config/plan_constants.py

@@ -0,0 +1,49 @@
+"""Constants for split-plan records, layer order, and title normalization."""
+
+from __future__ import annotations
+
+PLAN_SCHEMA_VERSION: int = 1
+PLAN_KEY_SCHEMA_VERSION: str = "schema_version"
+PLAN_KEY_SOURCE_COMMIT: str = "source_commit"
+PLAN_KEY_ALL_SLICES: str = "all_slices"
+PLAN_KEY_ALL_CHANGED_PATHS: str = "all_changed_paths"
+SLICE_KEY_ID: str = "id"
+SLICE_KEY_TITLE: str = "title"
+SLICE_KEY_LAYER: str = "layer"
+SLICE_KEY_ALL_PATHS: str = "all_paths"
+
+ALL_LAYER_ORDER: tuple[str, ...] = (
+    "config",
+    "backend",
+    "frontend",
+    "tests",
+    "docs",
+    "other",
+)
+ALL_LAYER_RANK_BY_NAME: dict[str, int] = {
+    each_layer: each_index for each_index, each_layer in enumerate(ALL_LAYER_ORDER)
+}
+UNKNOWN_LAYER_RANK: int = len(ALL_LAYER_ORDER)
+
+CONVENTIONAL_PREFIX_PATTERN: str = (
+    r"^(?P<prefix>feat|fix|docs|chore|refactor|test|ci|perf|build|style|revert)"
+    r"(?:\([^)]+\))?!?:\s*"
+)
+TITLE_PREFIX_SEPARATOR: str = ": "
+DEFAULT_TITLE_PREFIX: str = "chore"
+DEFAULT_SLICE_LAYER: str = "other"
+DEFAULT_EMPTY_TITLE_REMAINDER: str = "split slice"
+UTF8_ENCODING: str = "utf-8"
+GH_COMMAND: str = "gh"
+GH_API: str = "api"
+GH_PAGINATE_FLAG: str = "--paginate"
+GH_SLURP_FLAG: str = "--slurp"
+GH_PULLS_FILES_PATH_TEMPLATE: str = "repos/{owner}/{repo}/pulls/{pr_number}/files"
+GH_REST_FILE_FILENAME: str = "filename"
+FILE_KEY_PATH: str = "path"
+FILE_KEY_ADDITIONS: str = "additions"
+FILE_KEY_DELETIONS: str = "deletions"
+FILE_KEY_SHA: str = "sha"
+EXIT_CODE_SUCCESS: int = 0
+PATH_SEPARATOR: str = "/"
+VERIFY_PAYLOAD_KEY_OK: str = "ok"

package/skills/split-pr/scripts/config/split_pr_constants.py

@@ -0,0 +1,110 @@
+"""Thresholds and path markers for the hand-written line PR analyzer.
+
+::
+
+    hand_written_lines >= 200  -> requires_split_analysis
+    hand_written_lines >= 600  -> default_split (unless atomic_exception)
+"""
+
+from __future__ import annotations
+
+SPLIT_ANALYSIS_HAND_WRITTEN_LINE_THRESHOLD: int = 200
+"""Hand-written lines that require a recorded split analysis."""
+
+DEFAULT_SPLIT_HAND_WRITTEN_LINE_THRESHOLD: int = 600
+"""Hand-written lines that default to multiple PR slices."""
+
+EXIT_CODE_SUCCESS: int = 0
+EXIT_CODE_FAILURE: int = 1
+
+JSON_INDENT_SPACES: int = 2
+UTF8_ENCODING: str = "utf-8"
+
+CHURN_CLASS_HAND_WRITTEN: str = "hand_written"
+CHURN_CLASS_GENERATED: str = "generated"
+CHURN_CLASS_VENDOR: str = "vendor"
+CHURN_CLASS_MINIFIED: str = "minified"
+CHURN_CLASS_LOCKFILE: str = "lockfile"
+
+ALL_GENERATED_PATH_MARKERS: tuple[str, ...] = (
+    "/generated/",
+    ".generated.",
+    "/dist/",
+    "/build/",
+)
+
+ALL_VENDOR_PATH_MARKERS: tuple[str, ...] = (
+    "/vendor/",
+    "/third_party/",
+    "/node_modules/",
+)
+
+ALL_MINIFIED_SUFFIXES: tuple[str, ...] = (
+    ".min.js",
+    ".min.css",
+    ".min.mjs",
+)
+
+ALL_LOCKFILE_NAMES: frozenset[str] = frozenset(
+    {
+        "package-lock.json",
+        "yarn.lock",
+        "pnpm-lock.yaml",
+        "poetry.lock",
+        "Cargo.lock",
+        "Pipfile.lock",
+        "composer.lock",
+        "Gemfile.lock",
+    }
+)
+
+PAYLOAD_KEY_HAND_WRITTEN_LINES: str = "hand_written_lines"
+PAYLOAD_KEY_EXCLUDED_CHURN_LINES: str = "excluded_churn_lines"
+PAYLOAD_KEY_FILE_COUNT: str = "file_count"
+PAYLOAD_KEY_REQUIRES_SPLIT_ANALYSIS: str = "requires_split_analysis"
+PAYLOAD_KEY_DEFAULT_SPLIT: str = "default_split"
+PAYLOAD_KEY_ATOMIC_EXCEPTION: str = "atomic_exception"
+PAYLOAD_KEY_ALL_FILES: str = "all_files"
+PAYLOAD_KEY_ERROR: str = "error"
+PAYLOAD_KEY_FABLE_VERDICT: str = "fable_verdict"
+PAYLOAD_KEY_REASON: str = "reason"
+
+FILE_KEY_PATH: str = "path"
+FILE_KEY_ADDITIONS: str = "additions"
+FILE_KEY_DELETIONS: str = "deletions"
+FILE_KEY_CHURN_CLASS: str = "churn_class"
+FILE_KEY_CHANGED_LINES: str = "changed_lines"
+
+GH_COMMAND: str = "gh"
+GH_API_SUBCOMMAND: str = "api"
+GH_REPO_SUBCOMMAND: str = "repo"
+GH_VIEW: str = "view"
+GH_JSON_FLAG: str = "--json"
+GH_PAGINATE_FLAG: str = "--paginate"
+GH_SLURP_FLAG: str = "--slurp"
+GH_NAME_WITH_OWNER_FIELD: str = "nameWithOwner"
+GH_PULLS_FILES_PATH_TEMPLATE: str = "repos/{repo}/pulls/{pr_number}/files"
+GH_FILE_PATH: str = "path"
+GH_FILE_FILENAME: str = "filename"
+GH_FILE_ADDITIONS: str = "additions"
+GH_FILE_DELETIONS: str = "deletions"
+
+PLAN_KEY_SLICES: str = "slices"
+PLAN_KEY_PATHS: str = "paths"
+PLAN_KEY_STORY: str = "story"
+PLAN_KEY_IS_PREPARATORY_REFACTOR: str = "is_preparatory_refactor"
+PLAN_KEY_IS_VALID: str = "is_valid"
+PLAN_KEY_VIOLATIONS: str = "violations"
+
+VIOLATION_MISSING_PATH: str = "path_missing_from_all_slices"
+VIOLATION_DUPLICATE_PATH: str = "path_in_multiple_slices"
+VIOLATION_TEST_WITHOUT_BEHAVIOR: str = "test_slice_missing_related_behavior"
+VIOLATION_EMPTY_STORY: str = "slice_missing_story"
+
+ALL_TEST_PATH_MARKERS: tuple[str, ...] = (
+    "/test_",
+    "_test.py",
+    ".test.",
+    ".spec.",
+    "/tests/",
+)

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

@@ -0,0 +1,82 @@
+"""Materialize an entire split plan as ordered local commits.
+
+::
+
+    all_commit_records = materialize_plan_locally(repo, plan)
+    # one commit per slice in dependency topological order
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from config.dependency_constants import GRAPH_KEY_ORDER
+from config.git_operations_constants import RECORD_KEY_COMMIT_SHA
+from config.plan_constants import (
+    PLAN_KEY_ALL_SLICES,
+    PLAN_KEY_SOURCE_COMMIT,
+    SLICE_KEY_ALL_PATHS,
+    SLICE_KEY_ID,
+    SLICE_KEY_TITLE,
+)
+from split_pr_dependency_graph import build_dependency_graph
+from split_pr_git_operations import materialize_slice_commit, restore_repository_state
+from split_pr_process_runner import ProcessRunner, run_process
+from split_pr_script_types import JsonObject, validate_split_plan
+from verify_plan import verify_split_plan_coverage
+
+
+def materialize_plan_locally(
+    repository_path: Path,
+    all_plan: JsonObject,
+    run: ProcessRunner = run_process,
+) -> list[JsonObject]:
+    """Validate the plan, then commit each slice in topological layer order.
+
+    Args:
+        repository_path: Git repository root.
+        all_plan: Split-plan document (schema v1).
+        run: Process runner for git invocations.
+
+    Returns:
+        List of per-slice materialization records in commit order.
+
+    Raises:
+        ValueError: When the plan fails coverage or graph validation.
+        RuntimeError: When any git step fails; repository is restored to
+            the plan source_commit on failure.
+    """
+    verify_split_plan_coverage(all_plan)
+    validate_split_plan(all_plan)
+    source_commit = str(all_plan[PLAN_KEY_SOURCE_COMMIT])
+    all_slices = all_plan[PLAN_KEY_ALL_SLICES]
+    assert isinstance(all_slices, list)
+    graph = build_dependency_graph(all_slices)
+    order = graph[GRAPH_KEY_ORDER]
+    assert isinstance(order, list)
+    slice_by_id = {
+        str(each[SLICE_KEY_ID]): each
+        for each in all_slices
+        if isinstance(each, dict)
+    }
+    all_commit_records: list[JsonObject] = []
+    current_base = source_commit
+    try:
+        for each_slice_id in order:
+            each_slice = slice_by_id[str(each_slice_id)]
+            all_paths = each_slice[SLICE_KEY_ALL_PATHS]
+            assert isinstance(all_paths, list)
+            title = str(each_slice[SLICE_KEY_TITLE])
+            commit_record = materialize_slice_commit(
+                repository_path=repository_path,
+                all_slice_paths=[str(each) for each in all_paths],
+                commit_message=title,
+                expected_base_sha=current_base,
+                run=run,
+            )
+            all_commit_records.append(commit_record)
+            current_base = str(commit_record[RECORD_KEY_COMMIT_SHA])
+    except RuntimeError:
+        restore_repository_state(repository_path, source_commit, run)
+        raise
+    return all_commit_records

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

@@ -0,0 +1,212 @@
+"""Pack categorized files into review-budgeted split slices.
+
+::
+
+    plan = pack_files_into_slices(
+        source_commit="abc",
+        all_file_records=[{"path": "a.py", "additions": 50, "deletions": 0}],
+    )
+    # multi-file slices stay under the 200 hand-written budget;
+    # a single file may reach the 600 hard cap alone
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from categorize_files import annotate_files
+from config.packing_constants import (
+    ALL_BACKEND_SUFFIXES,
+    ALL_CONFIG_BASENAMES,
+    ALL_CONFIG_PATH_MARKERS,
+    ALL_DOC_SUFFIXES,
+    ALL_FRONTEND_SUFFIXES,
+    ALL_TEST_PATH_MARKERS,
+    EMPTY_HAND_WRITTEN_SLICE_ID,
+    EMPTY_HAND_WRITTEN_TITLE,
+    EXCLUDED_CHURN_LAYER_LABEL,
+    HARD_CAP_HAND_WRITTEN_LINES,
+    LAYER_BACKEND,
+    LAYER_CONFIG,
+    LAYER_DOCS,
+    LAYER_FRONTEND,
+    LAYER_OTHER,
+    LAYER_TESTS,
+    REVIEW_BUDGET_HAND_WRITTEN_LINES,
+    SLICE_ID_TEMPLATE,
+    SLICE_TITLE_TEMPLATE,
+)
+from config.plan_constants import (
+    SLICE_KEY_ALL_PATHS,
+    SLICE_KEY_ID,
+    SLICE_KEY_LAYER,
+    SLICE_KEY_TITLE,
+)
+from config.split_pr_constants import (
+    CHURN_CLASS_HAND_WRITTEN,
+    FILE_KEY_CHANGED_LINES,
+    FILE_KEY_CHURN_CLASS,
+    FILE_KEY_PATH,
+)
+from split_pr_script_types import JsonObject, build_split_plan, validate_split_plan
+
+
+def infer_path_layer(file_path: str) -> str:
+    """Map a path to a packing layer token.
+
+    Args:
+        file_path: Repository-relative path.
+
+    Returns:
+        One of config/backend/frontend/tests/docs/other.
+    """
+    normalized = file_path.replace("\\", "/").lower()
+    basename = Path(normalized).name
+    if basename in ALL_CONFIG_BASENAMES:
+        return LAYER_CONFIG
+    for each_marker in ALL_CONFIG_PATH_MARKERS:
+        if each_marker in f"/{normalized}/" or normalized.startswith(
+            each_marker.strip("/")
+        ):
+            return LAYER_CONFIG
+    for each_marker in ALL_TEST_PATH_MARKERS:
+        if each_marker in normalized:
+            return LAYER_TESTS
+    for each_suffix in ALL_DOC_SUFFIXES:
+        if normalized.endswith(each_suffix):
+            return LAYER_DOCS
+    for each_suffix in ALL_FRONTEND_SUFFIXES:
+        if normalized.endswith(each_suffix):
+            return LAYER_FRONTEND
+    for each_suffix in ALL_BACKEND_SUFFIXES:
+        if normalized.endswith(each_suffix):
+            return LAYER_BACKEND
+    return LAYER_OTHER
+
+
+def _slice_document(
+    slice_index: int,
+    layer_name: str,
+    all_paths: list[str],
+    title_layer: str | None = None,
+) -> JsonObject:
+    title_token = title_layer if title_layer is not None else layer_name
+    slice_id = SLICE_ID_TEMPLATE.format(index=slice_index, layer=layer_name)
+    slice_title = SLICE_TITLE_TEMPLATE.format(layer=title_token, index=slice_index)
+    return {
+        SLICE_KEY_ID: slice_id,
+        SLICE_KEY_TITLE: slice_title,
+        SLICE_KEY_LAYER: layer_name,
+        SLICE_KEY_ALL_PATHS: list(all_paths),
+    }
+
+
+def _pack_hand_written_slices(
+    all_hand_written: list[JsonObject],
+    review_budget: int,
+) -> list[JsonObject]:
+    all_slices: list[JsonObject] = []
+    open_layer: str | None = None
+    open_paths: list[str] = []
+    open_lines = 0
+    slice_index = 1
+
+    def flush_open() -> None:
+        nonlocal open_layer, open_paths, open_lines, slice_index
+        if open_layer is None or not open_paths:
+            open_layer = None
+            open_paths = []
+            open_lines = 0
+            return
+        all_slices.append(_slice_document(slice_index, open_layer, open_paths))
+        slice_index += 1
+        open_layer = None
+        open_paths = []
+        open_lines = 0
+
+    all_sorted = sorted(
+        all_hand_written,
+        key=lambda each: (
+            infer_path_layer(str(each[FILE_KEY_PATH])),
+            str(each[FILE_KEY_PATH]),
+        ),
+    )
+    for each_file in all_sorted:
+        path = str(each_file[FILE_KEY_PATH])
+        layer = infer_path_layer(path)
+        lines = int(each_file.get(FILE_KEY_CHANGED_LINES, 0) or 0)
+        if lines > HARD_CAP_HAND_WRITTEN_LINES:
+            raise ValueError(
+                f"file {path} has {lines} hand-written lines above hard cap "
+                f"{HARD_CAP_HAND_WRITTEN_LINES}"
+            )
+        if open_layer is not None and (
+            layer != open_layer or open_lines + lines > review_budget
+        ):
+            flush_open()
+        if open_layer is None:
+            open_layer = layer
+            open_paths = [path]
+            open_lines = lines
+        else:
+            open_paths.append(path)
+            open_lines += lines
+    flush_open()
+    return all_slices
+
+
+def pack_files_into_slices(
+    source_commit: str,
+    all_file_records: list[JsonObject],
+    review_budget: int = REVIEW_BUDGET_HAND_WRITTEN_LINES,
+) -> JsonObject:
+    """Annotate, layer, and pack files into budgeted slices, then build a plan.
+
+    Args:
+        source_commit: Exact commit the file list was taken from.
+        all_file_records: Path/additions/deletions maps.
+        review_budget: Max hand-written lines per slice (default 200).
+
+    Returns:
+        Validated split-plan document.
+
+    Raises:
+        ValueError: When a single file exceeds the hard 600-line cap alone,
+            or plan validation fails.
+    """
+    if review_budget < 1:
+        raise ValueError("review_budget must be positive")
+    all_annotated = annotate_files(all_file_records)
+    all_changed_paths = [str(each[FILE_KEY_PATH]) for each in all_annotated]
+    all_hand_written = [
+        each
+        for each in all_annotated
+        if each.get(FILE_KEY_CHURN_CLASS) == CHURN_CLASS_HAND_WRITTEN
+    ]
+    all_excluded = [
+        each
+        for each in all_annotated
+        if each.get(FILE_KEY_CHURN_CLASS) != CHURN_CLASS_HAND_WRITTEN
+    ]
+    all_slices = _pack_hand_written_slices(all_hand_written, review_budget)
+    if all_excluded:
+        all_slices.append(
+            _slice_document(
+                len(all_slices) + 1,
+                LAYER_OTHER,
+                [str(each[FILE_KEY_PATH]) for each in all_excluded],
+                title_layer=EXCLUDED_CHURN_LAYER_LABEL,
+            )
+        )
+    if not all_slices and all_changed_paths:
+        all_slices.append(
+            {
+                SLICE_KEY_ID: EMPTY_HAND_WRITTEN_SLICE_ID,
+                SLICE_KEY_TITLE: EMPTY_HAND_WRITTEN_TITLE,
+                SLICE_KEY_LAYER: LAYER_OTHER,
+                SLICE_KEY_ALL_PATHS: list(all_changed_paths),
+            }
+        )
+    plan = build_split_plan(source_commit, all_changed_paths, all_slices)
+    validate_split_plan(plan)
+    return plan

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

@@ -0,0 +1,70 @@
+"""Build a deterministic dependency graph over split-plan slices.
+
+::
+
+    graph = build_dependency_graph(all_slices)
+    # edges: lower-rank layers must land before higher-rank layers
+
+Empty input, empty or duplicate ids, and unknown layers raise ValueError.
+"""
+
+from __future__ import annotations
+
+from config.dependency_constants import (
+    EDGE_KEY_FROM,
+    EDGE_KEY_TO,
+    GRAPH_KEY_EDGES,
+    GRAPH_KEY_NODES,
+    GRAPH_KEY_ORDER,
+    ALL_LAYER_RANK_BY_NAME,
+)
+from config.plan_constants import SLICE_KEY_ID, SLICE_KEY_LAYER
+from split_pr_script_types import JsonObject
+
+
+def build_dependency_graph(all_slices: list[JsonObject]) -> JsonObject:
+    """Return nodes, layer-order edges, and a stable topological order.
+
+    Args:
+        all_slices: Slice maps with ``id`` and ``layer``.
+
+    Returns:
+        Graph document with nodes, edges, and topological_order.
+
+    Raises:
+        ValueError: When input is empty, a slice id is empty or duplicated,
+            or a layer is unknown.
+    """
+    if not all_slices:
+        raise ValueError("all_slices must be non-empty")
+    all_nodes: list[str] = []
+    all_layer_by_id: dict[str, str] = {}
+    for each_slice in all_slices:
+        slice_id = str(each_slice.get(SLICE_KEY_ID, "") or "")
+        if not slice_id:
+            raise ValueError("every slice needs a non-empty id")
+        if slice_id in all_layer_by_id:
+            raise ValueError(f"duplicate slice id: {slice_id}")
+        layer = str(each_slice.get(SLICE_KEY_LAYER, "other") or "other")
+        if layer not in ALL_LAYER_RANK_BY_NAME:
+            raise ValueError(f"unknown layer {layer!r} on slice {slice_id}")
+        all_nodes.append(slice_id)
+        all_layer_by_id[slice_id] = layer
+    all_edges: list[JsonObject] = []
+    for each_from in all_nodes:
+        for each_to in all_nodes:
+            if each_from == each_to:
+                continue
+            from_rank = ALL_LAYER_RANK_BY_NAME[all_layer_by_id[each_from]]
+            to_rank = ALL_LAYER_RANK_BY_NAME[all_layer_by_id[each_to]]
+            if from_rank < to_rank:
+                all_edges.append({EDGE_KEY_FROM: each_from, EDGE_KEY_TO: each_to})
+    all_order = sorted(
+        all_nodes,
+        key=lambda each_id: (ALL_LAYER_RANK_BY_NAME[all_layer_by_id[each_id]], each_id),
+    )
+    return {
+        GRAPH_KEY_NODES: all_nodes,
+        GRAPH_KEY_EDGES: all_edges,
+        GRAPH_KEY_ORDER: all_order,
+    }