docs: document the report output spec and pin it with golden tests

Add an output specification block above render_report showing the exact
success and failure layouts, and golden tests that assert the full
rendered report byte-for-byte so the spec stays accurate as the output
evolves.

Author: shenxianpeng

main.py

@@ -468,6 +468,69 @@ def _markdown_passed_details(results: list[ScopeResult]) -> str:
     return "\n".join(lines)
 
 
+# ---------------------------------------------------------------------------
+# Output specification
+#
+# The Markdown report shared by the job summary and the PR comment renders
+# as follows (values are filled from ScopeResult data):
+#
+# Success:
+#
+#   # Commit Check
+#
+#   ✅ **11 passed** (11 scopes)
+#
+#   <details>
+#   <summary>Show details</summary>
+#
+#   ```text
+#   Commit message
+#     ✔ PR title (feat: add login page)
+#     ✔ Commit 1/11 (feat: add user auth)
+#   Branch
+#     ✔ Branch (feature/add-login)
+#   Author
+#     ✔ Author name (Jane Doe)
+#     ✔ Author email (jane@example.com)
+#   ```
+#
+#   </details>
+#
+# Failure:
+#
+#   # Commit Check
+#
+#   ❌ **2 failures** · ✅ **9 passed** (11 scopes)
+#
+#   | Scope | Checked value | Failed checks | Result |
+#   |---|---|---|---|
+#   | Commit 2/11 | `bad msg` | [CC001 message](https://commit-check.com/rules/#cc001) | ❌ |
+#
+#   <details>
+#   <summary>Show details</summary>
+#
+#   ```text
+#   Commit message
+#     ✔ PR title (feat: add login page)
+#     ✖ Commit 2/11 (1 failure)
+#       CC001 message: The commit message should follow Conventional Commits.
+#       Suggest: Use <type>(<scope>): <description>
+#   Branch
+#     ✔ Branch (feature/add-login)
+#   ```
+#
+#   </details>
+#
+#   _Rules reference: https://commit-check.com/rules/_
+#
+# Notes:
+# - The table lists only failed scopes; passing scopes live in the details.
+# - Values are capped at 60 chars (… suffix) and shown for every scope in
+#   the details block, plus for failed scopes in the table.
+# - The step log output is a separate plain-text rendering (render_step_log).
+# ---------------------------------------------------------------------------
+
+
 def render_report(results: list[ScopeResult], include_footer: bool = True) -> str:
     """Render the Markdown report shared by the job summary and PR comment.
 

main_test.py

@@ -629,6 +629,74 @@ def test_raw_text_fallback_is_printed(self):
 
 
 class TestRenderJobSummary(unittest.TestCase):
+    def test_success_golden_output(self):
+        """Pin the full success report so the spec stays visible and exact."""
+        results = [
+            pass_scope("PR title", value="feat: add login page"),
+            pass_scope("Commit 1/2", value="feat: add user auth"),
+            pass_scope("Commit 2/2", value="fix: resolve timeout"),
+            pass_scope("Branch", value="feature/add-login"),
+        ]
+        body = main.render_report(results)
+        self.assertEqual(
+            body,
+            "# Commit Check\n"
+            "\n"
+            "✅ **4 passed** (4 scopes)\n"
+            "\n"
+            "<details>\n"
+            "<summary>Show details</summary>\n"
+            "\n"
+            "```text\n"
+            "Commit message\n"
+            "  ✔ PR title (feat: add login page)\n"
+            "  ✔ Commit 1/2 (feat: add user auth)\n"
+            "  ✔ Commit 2/2 (fix: resolve timeout)\n"
+            "Branch\n"
+            "  ✔ Branch (feature/add-login)\n"
+            "```\n"
+            "\n"
+            "</details>",
+        )
+
+    def test_failure_golden_output(self):
+        """Pin the full failure report: failed row in the table, all in details."""
+        results = [
+            pass_scope("PR title", value="feat: add login page"),
+            fail_scope("Commit 2/2"),
+            pass_scope("Branch", value="feature/add-login"),
+        ]
+        body = main.render_report(results)
+        self.assertEqual(
+            body,
+            "# Commit Check\n"
+            "\n"
+            "❌ **1 failure** · ✅ **2 passed** (3 scopes)\n"
+            "\n"
+            "| Scope | Checked value | Failed checks | Result |\n"
+            "|---|---|---|---|\n"
+            "| Commit 2/2 | `bad message` | "
+            "[CC001 message](https://commit-check.com/rules/#cc001) | ❌ |\n"
+            "\n"
+            "<details>\n"
+            "<summary>Show details</summary>\n"
+            "\n"
+            "```text\n"
+            "Commit message\n"
+            "  ✔ PR title (feat: add login page)\n"
+            "  ✖ Commit 2/2 (1 failure)\n"
+            "    CC001 message: The commit message should follow "
+            "Conventional Commits.\n"
+            "    Suggest: Use <type>(<scope>): <description>\n"
+            "Branch\n"
+            "  ✔ Branch (feature/add-login)\n"
+            "```\n"
+            "\n"
+            "</details>\n"
+            "\n"
+            "_Rules reference: https://commit-check.com/rules/_",
+        )
+
     def test_all_pass(self):
         body = main.render_job_summary([pass_scope("Branch", value="main")])
         self.assertTrue(body.startswith(main.REPORT_TITLE))