fix: print the failure reason once and keep the log tree intact

The job log showed the same sentence twice in a row under every failure:

    Error: Commit message should use imperative mood (...)
        value: feat: settle the report format ...
        Commit message should use imperative mood (...)

The first line was an ::error workflow command carrying the first line of the
error, the third was the listing printing the whole error underneath it.

The annotation also broke the listing it sat inside. An ::error renders as a
line of its own wherever it appears, so printing one between the ✖ scope line
and its details split the indented tree apart. And its title= — the only place
the rule ID was written — is shown in the annotations UI, never inline, so the
visible line lost the rule ID entirely.

Annotations are now emitted after every group, one per failure, with the scope
in the message since the title cannot carry it. The listing keeps the reason,
the rule ID, the value, the suggestion and the docs link, indented under the
scope that failed. Passing scopes show the value that was checked, which the
Markdown report already did.

Also drops the "(0 failures)" that unparsable output rendered next to its ✖:
there is no check list to count, and zero next to a cross reads as a
contradiction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn

Author: shenxianpeng

main.py

@@ -367,38 +367,72 @@ def _grouped(results: list[ScopeResult]) -> list[tuple[str, list[ScopeResult]]]:
     return groups
 
 
+def _annotation_escape(text: str) -> str:
+    """Escape text for a workflow command payload.
+
+    A newline would end the command and leave the rest of the message as a
+    stray log line, and a bare ``%`` can be read as the start of an escape.
+    """
+    return text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
 def render_step_log(results: list[ScopeResult]) -> None:
-    """Print results to the step log with folded groups and error annotations."""
+    """Print results to the step log, then emit one annotation per failure.
+
+    The two are separated deliberately. An ``::error`` command renders as a
+    line of its own wherever it is printed, so emitting one inside the indented
+    listing broke the tree apart, and its ``title=`` \u2014 which is what carries the
+    rule ID \u2014 is only shown in the annotations UI, never inline. Printing the
+    detail once in the listing and the annotations after all the groups keeps
+    the log readable and still surfaces failures in the run summary and on the
+    Files changed tab.
+    """
+    annotations: list[tuple[str, str]] = []
+
     for group_name, scopes in _grouped(results):
         print(f"::group::{group_name}")
         for scope in scopes:
+            value = _scope_value(scope)
+            suffix = f" ({value})" if value else ""
             if scope.status == "pass":
-                print(f"  \u2714 {scope.label}")
+                print(f"  \u2714 {scope.label}{suffix}")
                 continue
-            failures = scope.failures
-            count = f" ({len(failures)} failure{'s' if len(failures) != 1 else ''})"
-            print(f"  \u2716 {scope.label}{count}")
             if scope.raw_text and not scope.checks:
                 # Defensive fallback: commit-check produced unexpected output.
+                print(f"  \u2716 {scope.label}")
                 for line in scope.raw_text.strip().splitlines():
-                    print(f"    {line}")
+                    print(f"      {line}")
+                annotations.append(
+                    (f"commit-check: {scope.label}", "output could not be parsed")
+                )
                 continue
+            failures = scope.failures
+            count = f" ({len(failures)} failure{'s' if len(failures) != 1 else ''})"
+            print(f"  \u2716 {scope.label}{count}")
             for check in failures:
-                title = _rule_label(check)
+                label = _rule_label(check)
                 error = check.get("error", "")
-                first_line = error.splitlines()[0] if error else "check failed"
-                print(f"::error title={title}::{first_line}")
+                print(f"      {label}")
                 if check.get("value"):
-                    print(f"    value: {check['value']}")
+                    print(f"        value: {check['value']}")
                 if error:
-                    print(f"    {error}")
+                    for line in error.splitlines():
+                        print(f"        {line}")
                 if check.get("suggest"):
-                    print(f"    Suggest: {check['suggest']}")
+                    print(f"        Suggest: {check['suggest']}")
                 if check.get("docs_url"):
-                    print(f"    Docs: {check['docs_url']}")
+                    print(f"        Docs: {check['docs_url']}")
+                first_line = error.splitlines()[0] if error else "check failed"
+                annotations.append((label, f"{scope.label}: {first_line}"))
         print("::endgroup::")
 
-    if all(scope.status == "pass" for scope in results):
+    for title, message in annotations:
+        print(
+            f"::error title={_annotation_escape(title)}"
+            f"::{_annotation_escape(message)}"
+        )
+
+    if not annotations:
         print("\u2714 commit-check: all checks passed")
 
 

main_test.py

@@ -608,14 +608,58 @@ def test_failure_prints_group_and_error_annotation(self):
         self.assertIn("::group::Commit message", output)
         self.assertIn("::endgroup::", output)
         self.assertIn("✖ Commit 1/1 (1 failure)", output)
-        self.assertIn(
-            "::error title=CC001 message::The commit message should follow "
-            "Conventional Commits.",
-            output,
-        )
+        self.assertIn("      CC001 message", output)
         self.assertIn("value: bad message", output)
         self.assertIn("Suggest: Use <type>(<scope>): <description>", output)
         self.assertIn("Docs: https://commit-check.com/rules/#cc001", output)
+        # The annotation names the scope, which the title alone cannot carry.
+        self.assertIn(
+            "::error title=CC001 message::Commit 1/1: The commit message should "
+            "follow Conventional Commits.",
+            output,
+        )
+
+    def test_failure_reason_is_printed_once(self):
+        """The listing and the annotation must not both print the reason.
+
+        They used to: the ::error command carried the first line of the error
+        and the listing printed the whole error underneath it, so the same
+        sentence appeared twice in a row in the job log.
+        """
+        output = self._run([fail_scope("Commit 1/1")])
+        self.assertEqual(
+            output.count("The commit message should follow Conventional Commits."),
+            2,  # once in the listing, once in the annotation after the groups
+        )
+        listing = output.split("::endgroup::")[0]
+        self.assertEqual(
+            listing.count("The commit message should follow Conventional Commits."), 1
+        )
+
+    def test_annotations_come_after_every_group(self):
+        """An ::error inside a group breaks the indented listing apart."""
+        output = self._run([fail_scope("Commit 1/1"), pass_scope("Branch")])
+        self.assertLess(output.rindex("::endgroup::"), output.index("::error "))
+
+    def test_annotation_payload_is_escaped(self):
+        scope = main.ScopeResult(
+            label="Commit 1/1",
+            checks=[
+                make_check(
+                    "message",
+                    status="fail",
+                    error="first line\nsecond line with 100% certainty",
+                )
+            ],
+        )
+        output = self._run([scope])
+        annotation = [ln for ln in output.splitlines() if ln.startswith("::error")][0]
+        self.assertNotIn("\n", annotation.removeprefix("::error "))
+        self.assertIn("first line", annotation)
+
+    def test_pass_scopes_show_the_checked_value(self):
+        output = self._run([pass_scope("Branch", value="feature/add-login")])
+        self.assertIn("✔ Branch (feature/add-login)", output)
 
     def test_groups_scopes_by_category(self):
         results = [
@@ -632,8 +676,12 @@ def test_groups_scopes_by_category(self):
     def test_raw_text_fallback_is_printed(self):
         scope = main.ScopeResult(label="Branch", raw_text="unexpected output")
         output = self._run([scope])
-        self.assertIn("✖ Branch (0 failures)", output)
+        # No "(0 failures)": there is no check list to count, and claiming zero
+        # next to a ✖ reads as a contradiction.
+        self.assertIn("✖ Branch", output)
+        self.assertNotIn("0 failures", output)
         self.assertIn("unexpected output", output)
+        self.assertIn("::error title=commit-check: Branch::", output)
 
 
 class TestRenderJobSummary(unittest.TestCase):