feat(stack): embed JSON payload in stack comments (#1219)

Append a `` line to every stack comment
body, carrying schema_version, stack_id, and per-pull metadata
(number, change_id, head_sha, base_branch, dest_branch, is_current).
Thread stack_id (the local dest_branch) from stack_push down through
create_or_update_comments and _update_comment_for_pull.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jd

mergify_cli/stack/push.py

@@ -512,7 +512,13 @@ async def stack_push(
         ]
 
         with console.status("Updating comments..."):
-            await create_or_update_comments(client, user, repo, changes_to_comment)
+            await create_or_update_comments(
+                client,
+                user,
+                repo,
+                changes_to_comment,
+                stack_id=dest_branch,
+            )
 
         console.log("[green]Comments updated.[/]")
 
@@ -556,12 +562,45 @@ class StackComment:
         "This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):\n"
     )
 
-    def body(self, current_pull: github_types.PullRequest) -> str:
+    def _json_marker(
+        self,
+        current_pull: github_types.PullRequest,
+        stack_id: str,
+    ) -> str:
+        current_number = int(current_pull["number"])
+        payload = {
+            "schema_version": 1,
+            "stack_id": stack_id,
+            "pulls": [
+                {
+                    "number": int(change.pull["number"]),
+                    "change_id": change.id,
+                    "head_sha": change.commit_sha,
+                    "base_branch": change.base_branch,
+                    "dest_branch": change.dest_branch,
+                    "is_current": int(change.pull["number"]) == current_number,
+                }
+                for change in self.local_changes
+                if change.pull is not None
+            ],
+        }
+        return (
+            "<!-- mergify-stack-data: "
+            + json.dumps(payload, separators=(",", ":"))
+            + " -->"
+        )
+
+    def body(
+        self,
+        current_pull: github_types.PullRequest,
+        stack_id: str,
+    ) -> str:
         body = self.STACK_COMMENT_HEADER
         body += "\n"
         body += "| # | Pull Request | Link | |\n"
         body += "|--:|---|---|---|\n"
 
+        current_number = int(current_pull["number"])
         row = 0
         for change in self.local_changes:
             if change.pull is None:
@@ -570,9 +609,10 @@ def body(self, current_pull: github_types.PullRequest) -> str:
             pull = change.pull
             title = pull["title"].replace("|", "\\|")
             link = f"[#{pull['number']}]({pull['html_url']})"
-            status = "👈" if pull == current_pull else ""
+            status = "👈" if int(pull["number"]) == current_number else ""
             body += f"| {row} | {title} | {link} | {status} |\n"
 
+        body += self._json_marker(current_pull, stack_id) + "\n"
         return body
 
     @staticmethod
@@ -861,10 +901,11 @@ async def _update_comment_for_pull(
     repo: str,
     pull: github_types.PullRequest,
     stack_comment: StackComment,
+    stack_id: str,
     total_pulls: int,
     sem: asyncio.Semaphore,
 ) -> None:
-    new_body = stack_comment.body(pull)
+    new_body = stack_comment.body(pull, stack_id)
 
     async with sem:
         r = await client.get(
@@ -893,6 +934,7 @@ async def create_or_update_comments(
     user: str,
     repo: str,
     local_changes: list[changes.LocalChange],
+    stack_id: str,
 ) -> None:
     stack_comment = StackComment(local_changes)
     pulls = [c.pull for c in local_changes if c.pull is not None]
@@ -906,6 +948,7 @@ async def create_or_update_comments(
                 repo,
                 pull,
                 stack_comment,
+                stack_id,
                 len(pulls),
                 sem,
             )

mergify_cli/tests/stack/test_push.py

@@ -16,6 +16,7 @@
 
 import datetime
 import json
+import typing
 from typing import TYPE_CHECKING
 from unittest import mock
 
@@ -260,29 +261,35 @@ async def test_stack_create(
 
     # First stack comment is created
     assert len(post_comment1_mock.calls) == 1
-    expected_body = """This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):
-
-| # | Pull Request | Link | |
-|--:|---|---|---|
-| 1 | Title commit 1 | [#1](https://github.com/repo/user/pull/1) | 👈 |
-| 2 | Title commit 2 | [#2](https://github.com/repo/user/pull/2) |  |
-"""
-    assert json.loads(post_comment1_mock.calls.last.request.content) == {
-        "body": expected_body,
-    }
+    request_body1 = json.loads(post_comment1_mock.calls.last.request.content)["body"]
+    assert request_body1.startswith(
+        "This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):\n",
+    )
+    assert (
+        "| 1 | Title commit 1 | [#1](https://github.com/repo/user/pull/1) | 👈 |"
+        in request_body1
+    )
+    assert (
+        "| 2 | Title commit 2 | [#2](https://github.com/repo/user/pull/2) |  |"
+        in request_body1
+    )
+    assert "<!-- mergify-stack-data: " in request_body1
 
     # Second stack comment is created
     assert len(post_comment2_mock.calls) == 1
-    expected_body = """This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):
-
-| # | Pull Request | Link | |
-|--:|---|---|---|
-| 1 | Title commit 1 | [#1](https://github.com/repo/user/pull/1) |  |
-| 2 | Title commit 2 | [#2](https://github.com/repo/user/pull/2) | 👈 |
-"""
-    assert json.loads(post_comment2_mock.calls.last.request.content) == {
-        "body": expected_body,
-    }
+    request_body2 = json.loads(post_comment2_mock.calls.last.request.content)["body"]
+    assert request_body2.startswith(
+        "This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):\n",
+    )
+    assert (
+        "| 1 | Title commit 1 | [#1](https://github.com/repo/user/pull/1) |  |"
+        in request_body2
+    )
+    assert (
+        "| 2 | Title commit 2 | [#2](https://github.com/repo/user/pull/2) | 👈 |"
+        in request_body2
+    )
+    assert "<!-- mergify-stack-data: " in request_body2
 
 
 @pytest.mark.respx(base_url="https://api.github.com/")
@@ -2297,3 +2304,135 @@ async def test_push_branches_skips_notes_when_local_ref_absent(
         "commit1_sha:refs/heads/stack/title--29617d37",
         "+refs/notes/mergify/stack:refs/notes/mergify/stack",
     )
+
+
+def _make_local_change(
+    *,
+    change_id: str,
+    pull_number: int,
+    head_sha: str,
+    base_branch: str,
+    dest_branch: str,
+    title: str = "t",
+) -> tuple[changes.LocalChange, github_types.PullRequest]:
+    pull = typing.cast(
+        "github_types.PullRequest",
+        {
+            "number": pull_number,
+            "title": title,
+            "html_url": f"https://github.com/owner/repo/pull/{pull_number}",
+            "head": {"ref": dest_branch, "sha": head_sha},
+            "base": {"ref": base_branch},
+            "draft": False,
+            "merged_at": None,
+            "merge_commit_sha": None,
+            "body": "",
+            "state": "open",
+        },
+    )
+    change = changes.LocalChange(
+        id=changes.ChangeId(change_id),
+        pull=pull,
+        commit_sha=head_sha,
+        title=title,
+        message="",
+        base_branch=base_branch,
+        dest_branch=dest_branch,
+        action="update",
+    )
+    return change, pull
+
+
+def test_stack_comment_body_contains_json_marker() -> None:
+    c1, c1_pull = _make_local_change(
+        change_id="Iaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        pull_number=1,
+        head_sha="1111111111111111111111111111111111111111",
+        base_branch="main",
+        dest_branch="jd/feature/Iaaaaaaa",
+    )
+    c2, _ = _make_local_change(
+        change_id="Ibbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        pull_number=2,
+        head_sha="2222222222222222222222222222222222222222",
+        base_branch="jd/feature/Iaaaaaaa",
+        dest_branch="jd/feature/Ibbbbbbb",
+    )
+    comment = push.StackComment([c1, c2])
+    body = comment.body(c1_pull, stack_id="feature")
+
+    marker_prefix = "<!-- mergify-stack-data: "
+    marker_lines = [
+        line for line in body.splitlines() if line.startswith(marker_prefix)
+    ]
+    assert len(marker_lines) == 1
+    assert marker_lines[0].endswith(" -->")
+
+    payload = json.loads(marker_lines[0][len(marker_prefix) : -len(" -->")])
+    assert payload == {
+        "schema_version": 1,
+        "stack_id": "feature",
+        "pulls": [
+            {
+                "number": 1,
+                "change_id": "Iaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+                "head_sha": "1111111111111111111111111111111111111111",
+                "base_branch": "main",
+                "dest_branch": "jd/feature/Iaaaaaaa",
+                "is_current": True,
+            },
+            {
+                "number": 2,
+                "change_id": "Ibbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+                "head_sha": "2222222222222222222222222222222222222222",
+                "base_branch": "jd/feature/Iaaaaaaa",
+                "dest_branch": "jd/feature/Ibbbbbbb",
+                "is_current": False,
+            },
+        ],
+    }
+
+
+def test_stack_comment_is_current_flips_per_pull() -> None:
+    c1, _ = _make_local_change(
+        change_id="Iaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        pull_number=1,
+        head_sha="1111111111111111111111111111111111111111",
+        base_branch="main",
+        dest_branch="jd/feature/Iaaaaaaa",
+    )
+    c2, c2_pull = _make_local_change(
+        change_id="Ibbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+        pull_number=2,
+        head_sha="2222222222222222222222222222222222222222",
+        base_branch="jd/feature/Iaaaaaaa",
+        dest_branch="jd/feature/Ibbbbbbb",
+    )
+    comment = push.StackComment([c1, c2])
+
+    body2 = comment.body(c2_pull, stack_id="feature")
+    marker_line = next(
+        line
+        for line in body2.splitlines()
+        if line.startswith("<!-- mergify-stack-data: ")
+    )
+    payload = json.loads(marker_line[len("<!-- mergify-stack-data: ") : -len(" -->")])
+    assert [p["is_current"] for p in payload["pulls"]] == [False, True]
+
+
+def test_stack_comment_body_json_marker_is_single_line_compact() -> None:
+    c1, c1_pull = _make_local_change(
+        change_id="Iaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        pull_number=1,
+        head_sha="1111111111111111111111111111111111111111",
+        base_branch="main",
+        dest_branch="jd/feature/Iaaaaaaa",
+    )
+    comment = push.StackComment([c1])
+    body = comment.body(c1_pull, stack_id="feature")
+    marker_prefix = "<!-- mergify-stack-data: "
+    marker_line = next(
+        line for line in body.splitlines() if line.startswith(marker_prefix)
+    )
+    assert '", ' not in marker_line
+    assert '": ' not in marker_line