feat: Add --help, introduce "any" reason, explain filter when no notifications found

.gitignore

@@ -1,3 +1,4 @@
 coverage*/
 lib/
 node_modules/
+.aider*

src/cli.test.ts

@@ -39,6 +39,7 @@ describe("pruneGitHubNotificationsCLI", () => {
 				reason: new Set(["abc", "def"]),
 				title: [/abc.+def/],
 			},
+			logFilterWhenEmpty: true,
 		});
 		expect(mockRunInWatch).not.toHaveBeenCalled();
 	});
@@ -63,6 +64,7 @@ describe("pruneGitHubNotificationsCLI", () => {
 				reason: new Set(["abc", "def"]),
 				title: [/abc.+def/],
 			},
+			logFilterWhenEmpty: false,
 		});
 		expect(mockRunInWatch).toHaveBeenCalledWith(expect.any(Function), 10);
 	});

src/cli.ts

@@ -4,6 +4,27 @@ import * as z from "zod";
 import { pruneGitHubNotifications } from "./pruneGitHubNotifications.js";
 import { runInWatch } from "./runInWatch.js";
 
+function printHelp() {
+	console.log(`
+prune-github-notifications
+
+Prunes GitHub notifications you don't care about, such as automated dependency bumps. 🧹
+
+Options:
+  --auth       GitHub auth token (default: process.env.GH_TOKEN)
+  --bandwidth  Maximum parallel requests (default: 6)
+  --reason     Notification reason(s) to filter (default: "subscribed")
+  --title      Title regex pattern(s) to filter (default: dependency updates)
+  --watch      Seconds interval to continuously run (default: 0)
+  --help       Show this help message
+
+Examples:
+  npx prune-github-notifications
+  npx prune-github-notifications --reason subscribed --title "^chore.+ update .+ to"
+  npx prune-github-notifications --watch 10
+`);
+}
+
 const schema = z.object({
 	bandwidth: z.coerce.number().optional(),
 	reason: z
@@ -28,6 +49,9 @@ export async function pruneGitHubNotificationsCLI(args: string[]) {
 			bandwidth: {
 				type: "string",
 			},
+			help: {
+				type: "boolean",
+			},
 			reason: {
 				multiple: true,
 				type: "string",
@@ -43,6 +67,11 @@ export async function pruneGitHubNotificationsCLI(args: string[]) {
 		tokens: true,
 	});
 
+	if (values.help) {
+		printHelp();
+		return;
+	}
+
 	const { bandwidth, reason, title, watch } = schema.parse(values);
 
 	const action = async () =>
@@ -52,6 +81,7 @@ export async function pruneGitHubNotificationsCLI(args: string[]) {
 				reason,
 				title,
 			},
+			logFilterWhenEmpty: !watch,
 		});
 
 	await (watch ? runInWatch(action, watch) : action());

src/createThreadFilter.ts

@@ -11,6 +11,6 @@ export interface FilterableThreadSubject {
 
 export function createThreadFilter({ reason, title }: FilterOptions) {
 	return (thread: FilterableThread) =>
-		reason.has(thread.reason) &&
+		(reason.has("any") || reason.has(thread.reason)) &&
 		title.some((tester) => tester.test(thread.subject.title));
 }

src/pruneGitHubNotifications.test.ts

@@ -114,4 +114,27 @@ describe("pruneGitHubNotifications", () => {
 			]
 		`);
 	});
+
+	it("logs a message when no notifications match the filters", async () => {
+		vi.spyOn(console, "log").mockImplementation(() => {
+			// Noop
+		});
+
+		mockRequest.mockResolvedValueOnce({
+			data: [
+				{
+					id: "90",
+					reason: "different",
+					subject: {
+						title: "unmatched title",
+					},
+				},
+			],
+		});
+
+		const result = await pruneGitHubNotifications({ logFilterWhenEmpty: true });
+
+		expect(result.threads).toEqual([]);
+		expect(console.log).toHaveBeenCalled();
+	});
 });

src/pruneGitHubNotifications.ts

@@ -18,6 +18,7 @@ export async function pruneGitHubNotifications({
 	auth,
 	bandwidth = defaultOptions.bandwidth,
 	filters,
+	logFilterWhenEmpty = false,
 }: PruneGitHubNotificationsOptions = {}): Promise<PruneGitHubNotificationsResult> {
 	const octokit = await octokitFromAuth({ auth });
 
@@ -26,10 +27,13 @@ export async function pruneGitHubNotifications({
 			"X-GitHub-Api-Version": "2022-11-28",
 		},
 	});
-	const threadFilter = createThreadFilter({
+
+	const filtersWithDefaults = {
 		reason: filters?.reason ?? defaultOptions.filters.reason,
 		title: filters?.title ?? defaultOptions.filters.title,
-	});
+	};
+
+	const threadFilter = createThreadFilter(filtersWithDefaults);
 
 	// TODO: Why is the type not being friendly?
 	const throttle = (throttledQueue as unknown as ThrottledQueue)(
@@ -38,9 +42,19 @@ export async function pruneGitHubNotifications({
 		1000,
 	);
 
-	const threads = notifications.data
-		.filter(threadFilter)
-		.map((thread) => Number(thread.id));
+	const matchingThreads = notifications.data.filter(threadFilter);
+
+	if (matchingThreads.length === 0) {
+		if (logFilterWhenEmpty) {
+			console.log(
+				"No notifications found matching the filter criteria:",
+				filtersWithDefaults,
+			);
+		}
+		return { threads: [] };
+	}
+
+	const threads = matchingThreads.map((thread) => Number(thread.id));
 
 	await Promise.all(
 		threads.map(async (thread) => {

src/types.ts

@@ -7,6 +7,12 @@ export interface PruneGitHubNotificationsOptions {
 	auth?: string;
 	bandwidth?: number;
 	filters?: Partial<FilterOptions>;
+
+	/**
+	 * Controls whether or not to log when no notifications are found. This can
+	 * help new users understand the tool and what filters are being applied.
+	 */
+	logFilterWhenEmpty?: boolean;
 }
 
 export interface PruneGitHubNotificationsResult {