@d3lm/pr-stats 0.2.20 → 0.2.22

package/README.md

@@ -25,7 +25,7 @@ pr-stats
 
 Without flags, it covers PRs from the last 90 days across all repositories you can access.
 
-- **Queue** lists the open PRs awaiting your review with their wait time, and below them the open PRs you already reviewed. A fresh review request moves a PR back into the awaiting list. The `s` key snoozes a PR you are not ready to review yet, which parks it in a snoozed list until a time you pick. See [Snoozing](#snoozing).
+- **Awaiting you** splits into three sub-tabs, which the `t` key cycles. Awaiting review lists the open PRs awaiting your review with their wait time, Reviewed lists the open PRs you already reviewed, and Mentions is an inbox of the PRs that @-mention you. A fresh review request moves a PR back into the awaiting list. The `s` key snoozes a PR or a mention you are not ready for yet, which parks it in a snoozed list until a time you pick, and `d` marks a mention read. See [Mentions](#mentions) and [Snoozing](#snoozing).
 - **Your PRs** splits into your open PRs and a merged-and-closed report with merge-time, first-review, backlog, and outcome charts plus a reviewer leaderboard. The `t` key switches the sub-tabs.
 - **Reviews** counts the PRs you reviewed on request next to the review rounds they took, and charts your review times as a histogram, trend, heatmap, and weekly volume, plus review cycles, verdicts, an off-hours gauge, and the requests still waiting on you.
 - **PR size** carries the same charts for PR sizes and adds a weekly net-lines trend.
@@ -121,10 +121,13 @@ The Desktop notifications row in the settings dialog makes the TUI send a deskto
 ```json
 {
   "notifications": true,
+  "notifyMentions": true,
   "notifyChannel": "auto"
 }
 ```
 
+The Mention notifications row below it extends the notifications to @-mentions. While it is on together with the desktop notifications and the mention tracking described under [Mentions](#mentions), every load notifies you about a PR whose body, conversation comment, review, or inline review comment newly names you. The diff works like the one for review requests, so the first load with the setting on only records the mentions already there, and every later load reports the texts that newly mention you since the load before it. A text counts once, when it first shows up, so a comment that already mentioned you stays quiet when its author fixes a typo in it, and a PR that leaves the results and comes back does not report its old mentions again. A text that was edited to add the mention, or a review comment that was drafted earlier and published with its review, counts from the edit or the publication. The setting persists as `notifyMentions`.
+
 Notifications go through the terminal itself when it supports a notification escape sequence, which covers iTerm2, Kitty, Ghostty, WezTerm, and most VTE-based terminals like GNOME Terminal. The terminal posts the notification under its own notification permission and the sequence travels through SSH, so this path needs no setup beyond what the terminal asks for. Some terminals only show the banner while their window is unfocused. Terminals without such support get the platform's own command instead, the bundled `pr-stats.app` helper on macOS and `notify-send` on Linux. A notification that fails to send reports in the footer, for example when `notify-send` is missing on a Linux machine.
 
 The "Notification channel" row picks the path, and the choice persists as `notifyChannel` with the values `auto`, `terminal`, `command`, and `bell`. On `auto` the TUI tries the terminal first and falls back to the platform command, `terminal` and `command` force one of those paths, and `bell` rings the terminal bell instead of posting any text. The dialog shows the `command` value as the command's name on this platform. Forcing the command pays off inside editor terminals like the one in VS Code, which render the terminal path as a small in-editor toast instead of a system notification. The bell reaches every terminal, including the ones that swallow notifications, and each terminal turns it into its own signal, a sound, a flashing screen, a bell icon on the tab, or a badge on the dock icon. The "Send test notification" row below the channel names the channel the next send takes and sends a sample notification, so you can check that your desktop displays it before relying on it.
@@ -133,11 +136,25 @@ Two terminals accept the notification sequence without showing anything, and the
 
 On macOS the command path runs a small app bundle that ships inside the package, `dist/pr-stats.app`, so the banner carries the pr-stats name and icon and the app gets its own entry under System Settings › Notifications. The first send asks for permission the way any app does, and the helper waits for your answer, because macOS treats a prompt that goes unanswered until the requesting app quits as a refusal. Should notifications end up turned off, the footer says so, and the switch to turn them back on sits under System Settings › Notifications › pr-stats. The helper runs on macOS 13 and later on both Apple silicon and Intel Macs. A source checkout without the bundle falls back to `osascript`, whose notifications post under Script Editor and stay invisible since macOS 15 until Script Editor holds notification permission, which the Script Editor app grants after running the one-line script `display notification "test"` once.
 
+## Mentions
+
+The Mentions sub-tab of the Awaiting you tab is an inbox of the PRs that @-mention you. Its Unread list holds the PRs with a mention you have not handled, newest mention first, each row leading with the time since that mention, and its Read list at the bottom holds the ones you marked read. A mention is the exact login behind an at sign in a PR's body, a conversation comment, a review, or an inline review comment, written by someone else, so a team mention or a longer login that starts the same way does not count. Your own PRs count as well, because a mention asks for your attention no matter who opened the PR, and so do drafts and PRs that are already merged or closed. A PR can await your review and sit in the inbox at once, because a review request and a mention are two separate asks, and its row on the Awaiting review and the Reviewed sub-tabs carries an `@` badge in front of the title while the mention is unread, so you can see where a review also answers a question.
+
+The inbox starts empty. The first data with mentions seeds it, so only the mentions written after that point show up as unread, and a restart continues from the previous session's seed, listing what came in while the TUI was closed. Pressing `d` on a mention marks it read, which moves the PR into the Read list, where `d` marks it unread again and pulls it back into the Unread list. That also works on a PR whose mentions predate the seed. `D` marks every unread mention on screen read in one go. A new mention on a PR you already marked read brings the PR back into the Unread list, while an edit to a text you already handled does not, because the mark remembers which texts it covered. The read state is kept per account, so switching the account switches the inbox with it. The sub-tab has its own repo picker, which counts the unread, snoozed, and read mentions per repo, and `g` groups the aggregate by repo like the other queues. The `s` key snoozes a mention the way it snoozes a review request, see [Snoozing](#snoozing).
+
+The Track mentions row in the settings dialog turns the inbox on and off. It starts on, and while it is on every load runs two extra searches for the PRs that mention you, filtered on the last update instead of the creation date within the `since` window, because a fresh mention on an old PR is exactly what it looks for. Only the mentions written or edited within the window count, so a push or a comment on an old PR does not bring back a mention from before the window, and an unread mention you never handled drops out of the inbox once it ages past the window, the way a review request does. Widen `since` to see older mentions. One asks GitHub's mentions index, which only covers PR bodies and conversation comments, and the other looks for your login as text among the PRs you authored, commented on, reviewed, or are indexed as mentioned on, which reaches reviews and inline review comments too. A mention in a review of a PR you have only been asked to review, or have nothing to do with, stays out, because no search reaches those texts. Each load fetches the texts of the found PRs only when GitHub reports new activity on them since the last fetch, and confirms the mention against the texts, so the ongoing cost stays at those two searches. Turning it off skips the search, hides the inbox, and drops the seed, so turning it back on starts the inbox afresh. The setting persists as `trackMentions` in `settings.json`, and the read state persists in `mention-reads.json` in the cache directory, where it survives a restart and a cache clear.
+
+```json
+{
+  "trackMentions": true
+}
+```
+
 ## Snoozing
 
-A PR you commented on without leaving a review stays in the awaiting list, because GitHub still counts the review as requested. When you are waiting on the author, the `s` key snoozes the highlighted PR. A small dialog asks how long, starting from the default snooze duration, and takes a value in minutes, hours, days, or weeks like `30m`, `2h`, `1d`, or `1w`, up to four weeks. The PR then moves into a Snoozed list below the awaiting one, where its row shows the wake-up time instead of the wait, and the repo picker counts the snoozed PRs apart from the awaiting ones. Pressing `s` on a snoozed PR ends the snooze right away.
+A PR you commented on without leaving a review stays in the awaiting list, because GitHub still counts the review as requested. When you are waiting on the author, the `s` key snoozes the highlighted PR. A small dialog asks how long, starting from the default snooze duration, and takes a value in minutes, hours, days, or weeks like `30m`, `2h`, `1d`, or `1w`, up to four weeks. The PR then moves into a Snoozed list below the awaiting one, where its row shows the wake-up time instead of the wait, and the repo picker counts the snoozed PRs apart from the awaiting ones. Pressing `s` on a snoozed PR ends the snooze right away. The same key snoozes an unread mention on the Mentions sub-tab, which parks it in a Snoozed list between the Unread and the Read lists, and `d` on a snoozed mention marks it read and ends the snooze in one step.
 
-When the snooze ends and the PR still awaits your review, it moves back into the awaiting list, and a desktop notification says so while notifications are on. A PR that got reviewed, merged, or closed in the meantime ends its snooze quietly, and a review re-requested from you after the snooze voids it, so a re-request never hides behind a snooze. Snoozes persist in `snoozes.json` in the cache directory and survive a restart and a cache clear. A snooze that ended while the TUI was closed wakes up as soon as the TUI starts, so the restart reports it like the review requests that came in while it was closed.
+When the snooze ends and the PR still awaits your review, it moves back into the awaiting list, and a desktop notification says so while notifications are on. A snoozed mention comes back into the inbox the same way. A PR that got reviewed, merged, or closed in the meantime ends its snooze quietly, and a review re-requested from you after the snooze voids it, so a re-request never hides behind a snooze. A mention snooze works the same way, a mention you marked read ends it quietly and a newer mention voids it. Snoozes persist in `snoozes.json` in the cache directory and survive a restart and a cache clear. A snooze that ended while the TUI was closed wakes up as soon as the TUI starts, so the restart reports it like the review requests that came in while it was closed.
 
 The Default snooze row in the settings dialog sets the duration the dialog starts with, and the setting persists in `settings.json` in the cache directory.
 

package/dist/pr-stats.app/Contents/Info.plist

@@ -19,9 +19,9 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.2.20</string>
+	<string>0.2.22</string>
 	<key>CFBundleVersion</key>
-	<string>0.2.20</string>
+	<string>0.2.22</string>
 	<key>LSMinimumSystemVersion</key>
 	<string>13.0</string>
 	<key>LSUIElement</key>