refactor: action consistency before v1 release

[DerekRoberts]

Refactor: Unified, Consistent PR Extraction Logic for All Events

Refactor the action to use a single, consistent PR extraction flow for all event types. This will reduce maintenance burden, eliminate edge-case bugs, and ensure predictable outputs across all 145+ dependent repos—paving the way for a stable v1.0.0 release.

---

Steps

1. Design a Unified Extraction Function

   • Centralize PR extraction into one function in action.sh.
   • Extraction order:
     1. Use event context if available (e.g., GITHUB_EVENT_NUMBER for PR/merge queue events).
     2. Use GitHub API to map commit SHA to PR (for push, release, workflow_dispatch, etc.).
     3. Fallback: Scrub commit messages for PR number using strict end-of-line regex.
   • Standardize debug output to indicate which method was used.

2. Refactor Event Handling

   • Replace event-specific logic with calls to the unified extraction function.
   • Remove duplicated or inconsistent code paths.

3. Improve Error Handling

   • Ensure clear, actionable error messages if PR number cannot be determined.
   • Fail gracefully and log all attempted extraction methods.

4. Update Documentation

   • Clearly document the new extraction order and logic in README.
   • Add troubleshooting tips for edge cases.

5. Test Across All Event Types

   • Validate on PR, merge queue, push, release, and workflow_dispatch events.
   • Test on both standard and non-standard commit/merge scenarios.

6. Prepare for v1.0.0

   • Mark the new logic as a breaking change if any outputs or behaviors are altered.
   • Solicit feedback from maintainers of dependent repos before final release.

---

Decisions

• Centralizing logic increases maintainability and reliability.
• API-first with fallback ensures maximum compatibility.
• Standardized debug and error output aids troubleshooting.

---

Goal:
Deliver a robust, predictable, and easy-to-maintain action ready for v1.0.0, with clear upgrade guidance for all users.