feat: add pr-title input to validate pull request title

Add a new pr-title input that validates the PR title against the
Conventional Commits specification using commit-check's --message
check. This is especially useful for teams using Squash and Merge,
where the PR title becomes the final commit message.

Key changes:
- action.yml: add pr-title input (default: false)
- main.py: add get_pr_title(), PR_TITLE_ENABLED flag, integrate
  PR title validation into run_commit_check()
- main_test.py: add tests for get_pr_title(), PR title in
  run_commit_check(), and initial_emitted parameter

Closes #93

Author: shenxianpeng

action.yml

@@ -33,6 +33,10 @@ inputs:
     description: post results to the pull request comments
     required: false
     default: false
+  pr-title:
+    description: check pull request title following conventional commits
+    required: false
+    default: false
 runs:
   using: "composite"
   steps:
@@ -69,4 +73,5 @@ runs:
         DRY_RUN: ${{ inputs.dry-run }}
         JOB_SUMMARY: ${{ inputs.job-summary }}
         PR_COMMENTS: ${{ inputs.pr-comments }}
+        PR_TITLE: ${{ inputs.pr-title }}
         GITHUB_TOKEN: ${{ github.token }}

main.py

@@ -20,6 +20,7 @@
 DRY_RUN = os.getenv("DRY_RUN", "false")
 JOB_SUMMARY = os.getenv("JOB_SUMMARY", "false")
 PR_COMMENTS = os.getenv("PR_COMMENTS", "false")
+PR_TITLE = os.getenv("PR_TITLE", "false")
 GITHUB_STEP_SUMMARY = os.environ["GITHUB_STEP_SUMMARY"]
 
 
@@ -35,6 +36,7 @@ def env_flag(name: str, default: str = "false") -> bool:
 DRY_RUN_ENABLED = env_flag("DRY_RUN")
 JOB_SUMMARY_ENABLED = env_flag("JOB_SUMMARY")
 PR_COMMENTS_ENABLED = env_flag("PR_COMMENTS")
+PR_TITLE_ENABLED = env_flag("PR_TITLE")
 
 
 def log_env_vars():
@@ -45,14 +47,33 @@ def log_env_vars():
     print(f"AUTHOR_EMAIL = {AUTHOR_EMAIL}")
     print(f"DRY_RUN = {DRY_RUN}")
     print(f"JOB_SUMMARY = {JOB_SUMMARY}")
-    print(f"PR_COMMENTS = {PR_COMMENTS}\n")
+    print(f"PR_COMMENTS = {PR_COMMENTS}")
+    print(f"PR_TITLE = {PR_TITLE}\n")
 
 
 def is_pr_event() -> bool:
     """Return whether the workflow was triggered by a PR-style event."""
     return os.getenv("GITHUB_EVENT_NAME", "") in {"pull_request", "pull_request_target"}
 
 
+def get_pr_title() -> str | None:
+    """Read PR title from GitHub event payload."""
+    if not is_pr_event():
+        return None
+    event_path = os.getenv("GITHUB_EVENT_PATH")
+    if not event_path:
+        return None
+    try:
+        with open(event_path, "r") as f:
+            event = json.load(f)
+        return event.get("pull_request", {}).get("title")
+    except Exception as e:
+        print(
+            f"::warning::Failed to read PR title from event: {e}", file=sys.stderr
+        )
+        return None
+
+
 def parse_commit_messages(output: str) -> list[str]:
     """Split git log output into individual commit messages."""
     return [
@@ -149,13 +170,23 @@ def run_check_command(
     return result.returncode
 
 
-def run_pr_message_checks(pr_messages: list[str], result_file: TextIO) -> int:
+def run_pr_message_checks(
+    pr_messages: list[str],
+    result_file: TextIO,
+    initial_emitted: bool = False,
+) -> int:
     """Checks each PR commit message individually via commit-check --message.
 
+    Parameters
+    ----------
+    initial_emitted : bool
+        Whether another check (e.g. PR title) has already produced banner output,
+        so the first failing commit should use --no-banner.
+
     Returns 1 if any message fails, 0 if all pass.
     """
     has_failure = False
-    emitted_failure_output = False
+    emitted_failure_output = initial_emitted
     total = len(pr_messages)
     for index, msg in enumerate(pr_messages, start=1):
         command_args = ["--message"]
@@ -198,20 +229,59 @@ def build_check_args() -> list[str]:
 
 
 def run_commit_check() -> int:
-    """Runs the commit-check command and logs the result."""
+    """Runs all enabled checks and returns the overall exit code.
+
+    Checks are evaluated in order:
+      1. PR title (when ``pr-title: true`` and in a PR event)
+      2. Individual PR commit messages (when ``message: true`` and in a PR event)
+      3. All remaining checks (branch, author name/email, etc.)
+
+    Outside of a PR event all enabled checks are handed to the CLI at once.
+    """
     args = build_check_args()
+    exit_code = 0
+    emitted_failure_output = False
+
     with open("result.txt", "w") as result_file:
+        # ---- 1. PR title check ------------------------------------------------
+        if PR_TITLE_ENABLED and is_pr_event():
+            pr_title = get_pr_title()
+            if pr_title:
+                cmd_args = ["--message"]
+                output_prefix = None
+                if emitted_failure_output:
+                    cmd_args.append("--no-banner")
+                    output_prefix = "\n---\n# PR Title\n"
+                rc = run_check_command(
+                    cmd_args,
+                    result_file,
+                    input_text=pr_title,
+                    output_prefix=output_prefix,
+                )
+                if rc != 0:
+                    exit_code = max(exit_code, rc)
+                    emitted_failure_output = True
+
+        # ---- 2. Commit message checks -----------------------------------------
         if MESSAGE_ENABLED:
             pr_messages = get_pr_commit_messages()
             if pr_messages:
-                # In PR context: check each commit message individually to avoid
+                # In PR context: check each commit individually to avoid
                 # only validating the synthetic merge commit at HEAD.
-                message_rc = run_pr_message_checks(pr_messages, result_file)
-                other_args = [a for a in args if a != "--message"]
-                other_rc = run_other_checks(other_args, result_file)
-                return 1 if message_rc or other_rc else 0
-        # Non-PR context or message disabled: run all checks at once
-        return 1 if run_check_command(args, result_file) else 0
+                rc = run_pr_message_checks(
+                    pr_messages, result_file, initial_emitted=emitted_failure_output
+                )
+                if rc != 0:
+                    exit_code = max(exit_code, rc)
+                args = [a for a in args if a != "--message"]
+
+        # ---- 3. Remaining checks (branch, author, etc.) -----------------------
+        if args:
+            rc = run_other_checks(args, result_file)
+            if rc != 0:
+                exit_code = max(exit_code, rc)
+
+    return 1 if exit_code else 0
 
 
 def read_result_file() -> str | None:

main_test.py

@@ -67,6 +67,70 @@ def test_splits_messages_and_trims_surrounding_newlines(self):
         self.assertEqual(result, ["fix: first", "feat: second"])
 
 
+class TestGetPrTitle(unittest.TestCase):
+    def test_non_pr_event_returns_none(self):
+        with patch.dict(os.environ, {"GITHUB_EVENT_NAME": "push"}):
+            self.assertIsNone(main.get_pr_title())
+
+    def test_pr_event_returns_title(self):
+        import tempfile
+
+        event = {
+            "pull_request": {"title": "feat: add login page"},
+        }
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".json", delete=False
+        ) as f:
+            json.dump(event, f)
+            event_path = f.name
+        with (
+            patch.dict(os.environ, {"GITHUB_EVENT_NAME": "pull_request", "GITHUB_EVENT_PATH": event_path}),
+        ):
+            self.assertEqual(main.get_pr_title(), "feat: add login page")
+        os.unlink(event_path)
+
+    def test_pull_request_target_event(self):
+        import tempfile
+
+        event = {
+            "pull_request": {"title": "fix: resolve timeout"},
+        }
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".json", delete=False
+        ) as f:
+            json.dump(event, f)
+            event_path = f.name
+        with (
+            patch.dict(os.environ, {"GITHUB_EVENT_NAME": "pull_request_target", "GITHUB_EVENT_PATH": event_path}),
+        ):
+            self.assertEqual(main.get_pr_title(), "fix: resolve timeout")
+        os.unlink(event_path)
+
+    def test_missing_event_path_returns_none(self):
+        with (
+            patch.dict(os.environ, {"GITHUB_EVENT_NAME": "pull_request"}),
+            patch.dict(os.environ, {}, clear=True),
+        ):
+            os.environ["GITHUB_EVENT_NAME"] = "pull_request"
+            os.environ.pop("GITHUB_EVENT_PATH", None)
+            self.assertIsNone(main.get_pr_title())
+
+    def test_invalid_json_returns_none(self):
+        import tempfile
+
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".json", delete=False
+        ) as f:
+            f.write("not valid json")
+            event_path = f.name
+        with (
+            patch.dict(os.environ, {"GITHUB_EVENT_NAME": "pull_request", "GITHUB_EVENT_PATH": event_path}),
+            patch("builtins.print"),
+        ):
+            self.assertIsNone(main.get_pr_title())
+        os.unlink(event_path)
+
+
 class TestRunCheckCommand(unittest.TestCase):
     def test_with_args_calls_subprocess(self):
         mock_result = MagicMock(returncode=0, stdout="")
@@ -148,6 +212,32 @@ def test_first_failure_keeps_banner_and_later_failures_use_no_banner(self):
             ["commit-check", "--message", "--no-banner"],
         )
 
+    def test_initial_emitted_suppresses_banner_for_first_failure(self):
+        results = [
+            MagicMock(returncode=1, stdout="Commit rejected.\n"),
+        ]
+        with patch("main.subprocess.run", side_effect=results) as mock_run:
+            main.run_pr_message_checks(
+                ["bad commit"], io.StringIO(), initial_emitted=True
+            )
+        self.assertEqual(
+            mock_run.call_args[0][0],
+            ["commit-check", "--message", "--no-banner"],
+        )
+
+    def test_initial_not_emitted_allows_banner(self):
+        results = [
+            MagicMock(returncode=1, stdout="Commit rejected.\n"),
+        ]
+        with patch("main.subprocess.run", side_effect=results) as mock_run:
+            main.run_pr_message_checks(
+                ["bad commit"], io.StringIO(), initial_emitted=False
+            )
+        self.assertEqual(
+            mock_run.call_args[0][0],
+            ["commit-check", "--message"],
+        )
+
     def test_later_failure_prefix_uses_short_separator_without_extra_blank_lines(self):
         results = [
             MagicMock(returncode=0, stdout=""),
@@ -322,6 +412,75 @@ def test_pr_path_returns_nonzero_when_any_check_fails(self):
             rc = main.run_commit_check()
         self.assertEqual(rc, 1)
 
+    def test_pr_title_check_runs_when_enabled(self):
+        with (
+            patch("main.PR_TITLE_ENABLED", True),
+            patch("main.MESSAGE_ENABLED", False),
+            patch("main.BRANCH_ENABLED", False),
+            patch("main.AUTHOR_NAME_ENABLED", False),
+            patch("main.AUTHOR_EMAIL_ENABLED", False),
+            patch("main.is_pr_event", return_value=True),
+            patch("main.get_pr_title", return_value="feat: a feature"),
+            patch("main.run_check_command", return_value=0) as mock_cmd,
+            patch("main.run_other_checks", return_value=0),
+        ):
+            rc = main.run_commit_check()
+        self.assertEqual(rc, 0)
+        self.assertEqual(
+            mock_cmd.call_args[0][0], ["--message"],
+        )
+        self.assertEqual(mock_cmd.call_args[1]["input_text"], "feat: a feature")
+
+    def test_pr_title_failure_propagates(self):
+        with (
+            patch("main.PR_TITLE_ENABLED", True),
+            patch("main.MESSAGE_ENABLED", False),
+            patch("main.BRANCH_ENABLED", False),
+            patch("main.AUTHOR_NAME_ENABLED", False),
+            patch("main.AUTHOR_EMAIL_ENABLED", False),
+            patch("main.is_pr_event", return_value=True),
+            patch("main.get_pr_title", return_value="bad title"),
+            patch("main.run_check_command", return_value=1),
+            patch("main.run_other_checks", return_value=0),
+        ):
+            rc = main.run_commit_check()
+        self.assertEqual(rc, 1)
+
+    def test_pr_title_skipped_outside_pr_context(self):
+        with (
+            patch("main.PR_TITLE_ENABLED", True),
+            patch("main.MESSAGE_ENABLED", False),
+            patch("main.BRANCH_ENABLED", False),
+            patch("main.AUTHOR_NAME_ENABLED", False),
+            patch("main.AUTHOR_EMAIL_ENABLED", False),
+            patch("main.is_pr_event", return_value=False),
+            patch("main.get_pr_title") as mock_title,
+            patch("main.run_check_command", return_value=0),
+            patch("main.run_other_checks", return_value=0),
+        ):
+            rc = main.run_commit_check()
+        self.assertEqual(rc, 0)
+        mock_title.assert_not_called()
+
+    def test_pr_title_and_message_both_run(self):
+        with (
+            patch("main.PR_TITLE_ENABLED", True),
+            patch("main.MESSAGE_ENABLED", True),
+            patch("main.BRANCH_ENABLED", False),
+            patch("main.AUTHOR_NAME_ENABLED", False),
+            patch("main.AUTHOR_EMAIL_ENABLED", False),
+            patch("main.is_pr_event", return_value=True),
+            patch("main.get_pr_title", return_value="feat: nice pr"),
+            patch("main.get_pr_commit_messages", return_value=["fix: first", "feat: second"]),
+            patch("main.run_check_command", return_value=0) as mock_cmd,
+            patch("main.run_pr_message_checks", return_value=0) as mock_pr,
+            patch("main.run_other_checks", return_value=0),
+        ):
+            rc = main.run_commit_check()
+        self.assertEqual(rc, 0)
+        mock_cmd.assert_called_once()  # PR title check
+        mock_pr.assert_called_once()  # commit message checks
+
     def test_non_pr_path_uses_direct_command(self):
         with (
             patch("main.MESSAGE_ENABLED", True),