Use strict selector types for $ and exists helpers

Updated $ and exists helpers to use StrictlyParseSelector type from typed-query-selector, enabling compile-time validation of CSS selectors. Both helpers now accept template literal selector strings and infer the correct element types, while $ maintains an overload for explicit type specification when needed.

Co-authored-by: fregante <1402241+fregante@users.noreply.github.com>

Author: Copilot

global.d.ts

@@ -1,5 +1,4 @@
 /* eslint-disable @typescript-eslint/consistent-type-definitions -- Module augmentation */
-/// <reference path="./node_modules/typed-query-selector/strict.d.ts" />
 
 // Broaden types because testing against `"undefined"` is fine for our regexes
 interface RegExp {

index.ts

@@ -1,10 +1,27 @@
 import reservedNames from 'github-reserved-names/reserved-names.json' with {type: 'json'};
 import {addTests} from './collector.ts';
-
-// Selector helpers with typed-query-selector validation.
-// The generic parameter allows type override when selector inference isn't specific enough (e.g., attribute-only selectors)
-const $ = <E extends Element = Element>(selector: string) => document.querySelector<E>(selector);
-const exists = (selector: string): boolean => Boolean(document.querySelector(selector));
+import type {StrictlyParseSelector} from './strict-types.ts';
+
+// Selector helpers with typed-query-selector strict validation
+// Overload 1: Strict validation with type inference from selector
+function $<S extends string, E extends StrictlyParseSelector<S>>(
+	selector: S,
+): [E] extends [never] ? never : E | undefined;
+// Overload 2: Allow explicit type override when inference isn't specific enough
+function $<E extends Element>(selector: string): E | undefined;
+// Implementation
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return -- Return type is inferred from overloads
+function $(selector: string) {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-return -- Return type validated by strict typing
+	return document.querySelector(selector);
+}
+
+// @ts-expect-error -- E is inferred by TypeScript automatically, not used explicitly
+function exists<S extends string, E extends StrictlyParseSelector<S>>(selector: S): boolean {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- querySelector return type validated by strict typing
+	const element = document.querySelector(selector);
+	return Boolean(element);
+}
 
 const combinedTestOnly = ['combinedTestOnly']; // To be used only to skip tests of combined functions, i.e. isPageA() || isPageB()
 
@@ -297,6 +314,7 @@ TEST: addTests('isQuickPR', [
 	'https://github.com/sindresorhus/refined-github/compare/test-branch?quick_pull=1',
 ]);
 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call -- Strict validation may mark complex selectors as potentially invalid
 const getStateLabel = (): string | undefined => $([
 	'.State', // Old view
 	// React versions
@@ -402,6 +420,7 @@ export const isEmptyRepo = (): boolean => exists('[aria-label="Cannot fork becau
 
 export const isPublicRepo = (): boolean => exists('meta[name="octolytics-dimension-repository_public"][content="true"]');
 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-call -- Strict validation may mark selectors with child combinators as potentially invalid
 export const isArchivedRepo = (): boolean => Boolean(isRepo() && $('main > .flash-warn')?.textContent!.includes('archived'));
 
 export const isBlank = (): boolean => exists('main .blankslate:not([hidden] .blankslate)');
@@ -861,6 +880,7 @@ TEST: addTests('isNewRepoTemplate', [
 ]);
 
 /** Get the logged-in user’s username */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call -- getAttribute is safe
 const getLoggedInUser = (): string | undefined => $('meta[name="user-login"]')?.getAttribute('content') ?? undefined;
 
 /** Drop all redundant slashes */

strict-types.d.ts

@@ -0,0 +1,27 @@
+// Import the StrictlyParseSelector type for strict validation
+import type {StrictlyParseSelector} from 'typed-query-selector/parser';
+
+// Import strict types from typed-query-selector
+/* eslint-disable @typescript-eslint/consistent-type-definitions -- Global augmentation requires interface */
+declare global {
+	interface ParentNode {
+		querySelector<S extends string, E extends StrictlyParseSelector<S>>(
+			selector: S,
+		): [E] extends [never] ? never : E | undefined;
+
+		querySelectorAll<S extends string, E extends StrictlyParseSelector<S>>(
+			selector: S,
+		): [E] extends [never] ? never : NodeListOf<E>;
+	}
+
+	interface Element {
+		closest<S extends string, E extends StrictlyParseSelector<S>>(
+			selector: S,
+		): [E] extends [never] ? never : E | undefined;
+	}
+}
+/* eslint-enable @typescript-eslint/consistent-type-definitions */
+
+// Export the type for use in index.ts
+
+export {type StrictlyParseSelector} from 'typed-query-selector/parser';

tsconfig.json

@@ -8,6 +8,7 @@
 		"index.ts",
 		"index.test.ts",
 		"global.d.ts",
+		"strict-types.d.ts",
 		"collector.ts"
 	]
 }