chore: better base detection debug (#894)

This change introduces the source of where we found the base/head sha
This will help debuging Customer CI.

Author: sileht

mergify_cli/ci/cli.py

@@ -237,13 +237,19 @@ def scopes(
     head: str | None = None,
     base: str | None = None,
 ) -> None:
-    ref = git_refs_detector.detect()
+    if base or head:
+        ref = git_refs_detector.References(
+            base=base,
+            head=head or "HEAD",
+            source="manual",
+        )
+    else:
+        ref = git_refs_detector.detect()
+
     try:
         scopes = scopes_cli.detect(
             config_path=config_path,
-            base=base or ref.base,
-            head=head or ref.head,
-            is_merge_queue=ref.is_merge_queue,
+            references=ref,
         )
     except scopes_exc.ScopesError as e:
         raise click.ClickException(str(e)) from e

mergify_cli/ci/git_refs/detector.py

@@ -107,11 +107,21 @@ def _detect_base_from_push_event(ev: dict[str, typing.Any]) -> str | None:
     return None
 
 
+ReferencesSource = typing.Literal[
+    "manual",
+    "merge_queue",
+    "fallback_last_commit",
+    "github_event_other",
+    "github_event_pull_request",
+    "github_event_push",
+]
+
+
 @dataclasses.dataclass
 class References:
     base: str | None
     head: str
-    is_merge_queue: bool
+    source: ReferencesSource
 
     def maybe_write_to_github_outputs(self) -> None:
         gha = os.environ.get("GITHUB_OUTPUT")
@@ -135,37 +145,41 @@ def detect() -> References:
         event_name, event = utils.get_github_event()
     except utils.GitHubEventNotFoundError:
         # fallback to last commit
-        return References("HEAD^", "HEAD", is_merge_queue=False)
+        return References("HEAD^", "HEAD", "fallback_last_commit")
     else:
         if event_name in PULL_REQUEST_EVENTS:
             head = _detect_head_from_event(event) or "HEAD"
             # 0) merge-queue PR override
             mq_sha = _detect_base_from_merge_queue_payload(event)
             if mq_sha:
-                return References(mq_sha, head, is_merge_queue=True)
+                return References(mq_sha, head, "merge_queue")
 
             # 1) standard event payload
             event_sha = _detect_base_from_event(event)
             if event_sha:
-                return References(event_sha, head, is_merge_queue=False)
+                return References(event_sha, head, "github_event_pull_request")
 
             # 2) standard event payload
             event_sha = _detect_default_branch_from_event(event)
             if event_sha:
-                return References(event_sha, head, is_merge_queue=False)
+                return References(
+                    event_sha,
+                    head,
+                    "github_event_pull_request",
+                )
 
         elif event_name == "push":
             head_sha = _detect_head_from_push_event(event) or "HEAD"
             base_sha = _detect_base_from_push_event(event)
             if base_sha:
-                return References(base_sha, head_sha, is_merge_queue=False)
+                return References(base_sha, head_sha, "github_event_push")
 
             event_sha = _detect_default_branch_from_event(event)
             if event_sha:
-                return References(event_sha, "HEAD", is_merge_queue=False)
+                return References(event_sha, "HEAD", "github_event_push")
 
         else:
-            return References(None, "HEAD", is_merge_queue=False)
+            return References(None, "HEAD", "github_event_other")
 
     msg = "Could not detect base SHA. Provide GITHUB_EVENT_NAME / GITHUB_EVENT_PATH."
     raise BaseNotFoundError(msg)

mergify_cli/ci/scopes/cli.py

@@ -20,6 +20,8 @@
 if typing.TYPE_CHECKING:
     from collections import abc
 
+    from mergify_cli.ci.git_refs import detector as git_refs_detector
+
 GITHUB_ACTIONS_SCOPES_OUTPUT_NAME = "scopes"
 
 
@@ -93,8 +95,7 @@ def maybe_write_github_outputs(
 
 
 def maybe_write_github_step_summary(
-    base: str | None,
-    head: str,
+    references: git_refs_detector.References,
     all_scopes: abc.Iterable[str],
     scopes_hit: set[str],
 ) -> None:
@@ -103,8 +104,8 @@ def maybe_write_github_step_summary(
         return
     # Build a pretty Markdown table with emojis
     markdown = "## Mergify CI Scope Matching Results"
-    if base is not None:
-        markdown += f" for `{base}...{head}`"
+    if references.base is not None:
+        markdown += f" for `{references.base[:7]}...{references.head[:7]}` (source: `{references.source}`)"
     markdown += "\n\n"
     markdown += "| 🎯 Scope | ✅ Match |\n|:--|:--|\n"
     for scope in sorted(all_scopes):
@@ -138,15 +139,14 @@ def load_from_file(cls, filename: str) -> DetectedScope:
 def detect(
     config_path: str,
     *,
-    base: str | None,
-    head: str,
-    is_merge_queue: bool,
+    references: git_refs_detector.References,
 ) -> DetectedScope:
     cfg = config.Config.from_yaml(config_path)
 
-    if base is not None:
-        click.echo(f"Base: {base}")
-    click.echo(f"Head: {head}")
+    if references.base is not None:
+        click.echo(f"Base: {references.base}")
+    click.echo(f"Head: {references.head}")
+    click.echo(f"Source: {references.source}")
 
     scopes_hit: set[str]
     per_scope: dict[str, list[str]]
@@ -158,12 +158,12 @@ def detect(
         per_scope = {}
     elif isinstance(source, config.SourceFiles):
         all_scopes = set(source.files.keys())
-        if base is None:
+        if references.base is None:
             click.echo("No base provided, selecting all scopes")
             scopes_hit = set(source.files.keys())
             per_scope = {}
         else:
-            changed = changed_files.git_changed_files(base, head)
+            changed = changed_files.git_changed_files(references.base, references.head)
             click.echo("Changed files detected:")
             for file in changed:
                 click.echo(f"- {file}")
@@ -177,7 +177,7 @@ def detect(
 
     if cfg.scopes.merge_queue_scope is not None:
         all_scopes.add(cfg.scopes.merge_queue_scope)
-        if is_merge_queue:
+        if references.source == "merge_queue":
             scopes_hit.add(cfg.scopes.merge_queue_scope)
 
     if scopes_hit:
@@ -192,8 +192,7 @@ def detect(
 
     maybe_write_github_outputs(all_scopes, scopes_hit)
     maybe_write_github_step_summary(
-        base,
-        head,
+        references,
         all_scopes,
         scopes_hit,
     )

mergify_cli/tests/ci/git_refs/test_git_refs_detector.py

@@ -27,7 +27,10 @@ def test_detect_base_from_repository_default_branch(
 
     result = detector.detect()
 
-    assert result == detector.References("main", "HEAD", is_merge_queue=False)
+    expected_base_source: detector.ReferencesSource = (
+        "github_event_push" if event_name == "push" else "github_event_pull_request"
+    )
+    assert result == detector.References("main", "HEAD", expected_base_source)
 
 
 def test_maybe_write_github_outputs(
@@ -71,7 +74,7 @@ def test_detect_base_from_push_event(
     assert result == detector.References(
         "abc123",
         "xyz987",
-        is_merge_queue=False,
+        "github_event_push",
     )
 
 
@@ -96,7 +99,7 @@ def test_detect_base_from_pull_request_event_path(
     assert result == detector.References(
         "abc123",
         "xyz987",
-        is_merge_queue=False,
+        "github_event_pull_request",
     )
 
 
@@ -119,7 +122,7 @@ def test_detect_base_merge_queue_override(
 
     result = detector.detect()
 
-    assert result == detector.References("xyz789", "HEAD", is_merge_queue=True)
+    assert result == detector.References("xyz789", "HEAD", "merge_queue")
 
 
 def test_detect_base_no_info(
@@ -194,4 +197,4 @@ def test_detect_unhandled_event(
 
     result = detector.detect()
 
-    assert result == detector.References(None, "HEAD", is_merge_queue=False)
+    assert result == detector.References(None, "HEAD", "github_event_other")

mergify_cli/tests/ci/scopes/test_cli.py

@@ -8,6 +8,7 @@
 import respx
 import yaml
 
+from mergify_cli.ci.git_refs import detector as git_refs_detector
 from mergify_cli.ci.scopes import cli
 from mergify_cli.ci.scopes import config
 from mergify_cli.ci.scopes import exceptions
@@ -313,10 +314,18 @@ def test_maybe_write_github_step_summary(
     all_scopes = ["backend", "frontend", "docs"]
     scopes_hit = {"backend", "docs"}
 
-    cli.maybe_write_github_step_summary("da26838", "HEAD", all_scopes, scopes_hit)
+    cli.maybe_write_github_step_summary(
+        git_refs_detector.References(
+            "da26838azertyuiopqsdfghjkxcvbn",
+            "HEAD",
+            "github_event_pull_request",
+        ),
+        all_scopes,
+        scopes_hit,
+    )
 
     content = output_file.read_text()
-    expected = """## Mergify CI Scope Matching Results for `da26838...HEAD`
+    expected = """## Mergify CI Scope Matching Results for `da26838...HEAD` (source: `github_event_pull_request`)
 
 | 🎯 Scope | ✅ Match |
 |:--|:--|
@@ -364,9 +373,7 @@ def test_detect_with_matches(
     with mock.patch("click.echo") as mock_echo:
         result = cli.detect(
             str(config_file),
-            base="old",
-            head="new",
-            is_merge_queue=True,
+            references=git_refs_detector.References("old", "new", "merge_queue"),
         )
 
     # Verify calls
@@ -403,9 +410,11 @@ def test_detect_manual(
     ):
         cli.detect(
             str(config_file),
-            base="old",
-            head="new",
-            is_merge_queue=False,
+            references=git_refs_detector.References(
+                "old",
+                "new",
+                "github_event_pull_request",
+            ),
         )
 
 
@@ -432,14 +441,17 @@ def test_detect_no_base(
     with mock.patch("click.echo") as mock_echo:
         result = cli.detect(
             str(config_file),
-            base=None,
-            head="HEAD",
-            is_merge_queue=False,
+            references=git_refs_detector.References(
+                None,
+                "HEAD",
+                "fallback_last_commit",
+            ),
         )
 
     # Verify output
     calls = [call.args[0] for call in mock_echo.call_args_list]
     assert "Head: HEAD" in calls
+    assert "Source: fallback_last_commit" in calls
     assert "Scopes touched:" in calls
     assert "- backend" in calls
     assert "- frontend" in calls
@@ -468,9 +480,11 @@ def test_detect_no_matches(
     with mock.patch("click.echo") as mock_echo:
         result = cli.detect(
             str(config_file),
-            base="old",
-            head="new",
-            is_merge_queue=False,
+            references=git_refs_detector.References(
+                "old",
+                "new",
+                "github_event_pull_request",
+            ),
         )
 
     # Verify output
@@ -520,9 +534,11 @@ def test_detect_debug_output(
     with mock.patch("click.echo") as mock_echo:
         result = cli.detect(
             str(config_file),
-            base="old",
-            head="new",
-            is_merge_queue=False,
+            references=git_refs_detector.References(
+                "old",
+                "new",
+                "github_event_pull_request",
+            ),
         )
     # Verify debug output includes file details
     calls = [call.args[0] for call in mock_echo.call_args_list]