Improve resolve conflicts script (open-telemetry#18606)

Author: trask

.github/scripts/pr-triage/resolve_conflicts.py

@@ -6,6 +6,7 @@
 import argparse
 import sys
 from pathlib import Path
+from typing import TypedDict
 
 from common import (
     Summary,
@@ -21,6 +22,15 @@
 )
 
 
+CONFLICT_STAGES = ((1, "base"), (2, "ours-head"), (3, "theirs-merge-head"))
+
+
+class ConflictEntry(TypedDict):
+    path: str
+    conflict_diff: str
+    stage_snapshots: list[str]
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("pr", type=int, help="pull request number")
@@ -30,21 +40,71 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
+def safe_conflict_name(path: str) -> str:
+    return path.replace("/", "__").replace("\\", "__")
+
+
+def write_stage_snapshot(directory: Path, path: str, summary: Summary) -> list[str]:
+    stage_paths: list[str] = []
+    for stage, label in CONFLICT_STAGES:
+        result = git(["show", f":{stage}:{path}"], summary, check=False)
+        if result.returncode != 0:
+            continue
+        snapshot_path = directory / f"{safe_conflict_name(path)}.{label}"
+        snapshot_path.write_text(result.stdout, encoding="utf-8")
+        stage_paths.append(str(snapshot_path))
+    return stage_paths
+
+
 def write_conflict_bundle(directory: Path, summary: Summary) -> Path:
     progress(f"Preparing merge conflict bundle in {directory}")
     directory.mkdir(parents=True, exist_ok=True)
     files = unmerged_paths(summary)
-    write_json(directory / "conflicts.json", {"files": files})
+    staged_versions_dir = directory / "staged-versions"
+    staged_versions_dir.mkdir(parents=True, exist_ok=True)
+
+    conflicts: list[ConflictEntry] = []
     (directory / "status.txt").write_text(git(["status", "--porcelain"], summary).stdout, encoding="utf-8")
     (directory / "head-log.txt").write_text(git(["log", "--oneline", "-n", "20", "HEAD"], summary).stdout, encoding="utf-8")
     (directory / "merge-head-log.txt").write_text(git(["log", "--oneline", "-n", "20", "MERGE_HEAD"], summary).stdout, encoding="utf-8")
     for path in files:
-        safe_name = path.replace("/", "__").replace("\\", "__")
-        (directory / f"{safe_name}.diff").write_text(git(["diff", "--", path], summary).stdout, encoding="utf-8")
+        safe_name = safe_conflict_name(path)
+        diff_path = directory / f"{safe_name}.diff"
+        diff_path.write_text(git(["diff", "--", path], summary).stdout, encoding="utf-8")
+        conflicts.append(
+            {
+                "path": path,
+                "conflict_diff": str(diff_path),
+                "stage_snapshots": write_stage_snapshot(staged_versions_dir, path, summary),
+            }
+        )
+    write_json(directory / "conflicts.json", {"files": conflicts})
     plan = directory / "conflict-plan.md"
     lines = ["# Merge Conflict Resolution Plan", "", "## Conflicted Files", ""]
-    lines.extend(f"- {path}" for path in files)
-    lines.extend(["", "## Context", "", f"- Status: {directory / 'status.txt'}", f"- HEAD log: {directory / 'head-log.txt'}", f"- MERGE_HEAD log: {directory / 'merge-head-log.txt'}", ""])
+    for conflict in conflicts:
+        lines.append(f"- {conflict['path']}")
+        lines.append(f"  - Conflict diff: {conflict['conflict_diff']}")
+        for stage_snapshot in conflict["stage_snapshots"]:
+            lines.append(f"  - Stage snapshot: {stage_snapshot}")
+    lines.extend(
+        [
+            "",
+            "## Context",
+            "",
+            f"- Status: {directory / 'status.txt'}",
+            f"- HEAD log: {directory / 'head-log.txt'}",
+            f"- MERGE_HEAD log: {directory / 'merge-head-log.txt'}",
+            "",
+            "## Resolution Checklist",
+            "",
+            "- Inspect each conflict diff and all available stage snapshots before editing.",
+            "- Identify what behavior HEAD changed and what behavior MERGE_HEAD changed.",
+            "- Preserve both behaviors when they can coexist.",
+            "- If one side is intentionally dropped, record why it is obsolete or incompatible.",
+            "- After editing, compare the resolved file against both sides before staging it.",
+            "",
+        ]
+    )
     plan.write_text("\n".join(lines), encoding="utf-8")
     summary.temp_dir = str(directory)
     return plan
@@ -64,7 +124,10 @@ def copilot_prompt(plan_path: Path) -> str:
 - Do not push.
 - Do not rebase, abort, restart, or use force operations.
 - Resolve only the conflicted files listed in the bundle.
-- Preserve the intent of both HEAD and MERGE_HEAD when they can coexist.
+- For each conflicted file, inspect the conflict diff plus the available stage snapshots before editing: base, ours-HEAD, and theirs-MERGE_HEAD.
+- Preserve the intent of both HEAD and MERGE_HEAD when they can coexist; do not remove helpers, validation, generated bundle content, tests, or workflow steps from either side unless they are clearly obsolete after the merge.
+- If you choose one side over the other, explain why the dropped side is incompatible or superseded.
+- After editing each file, compare the resolved result against both side snapshots before staging it.
 - If the conflict requires product judgment or involves binary/non-text files, stop and explain.
 - Stage only files that you resolved.
 - When done, print a concise summary of each resolved file.