style: fix JSDoc formatting across codebase

scripts/readGithubCookies.ts

@@ -5,7 +5,6 @@ import logger from "../src/utils/logger";
 
 /**
  * Checks if a string matches the basic JWT format
- *
  * @param str - The string to check
  * @returns True if the string matches JWT format, false otherwise
  * @example
@@ -38,10 +37,14 @@ export function isJWT(str: string): boolean {
 }
 
 /**
- * Prints information about a single cookie
- *
+ * Prints information about a cookie and checks if it's a JWT
  * @param cookie - The cookie to print information about
  * @returns Whether this was a JWT cookie
+ * @example
+ * ```typescript
+ * const cookie = { name: 'session', value: 'xyz', domain: 'github.com' };
+ * const isJwt = printCookieInfo(cookie);
+ * ```
  */
 function printCookieInfo(cookie: ExportedCookie): boolean {
   logger.info("Name: %s", cookie.name);
@@ -67,10 +70,14 @@ function printCookieInfo(cookie: ExportedCookie): boolean {
 }
 
 /**
- * Prints a summary of the cookie search results
- *
+ * Prints a summary of found cookies and JWT count
  * @param cookies - The found cookies
  * @param jwtCount - Number of JWT cookies found
+ * @example
+ * ```typescript
+ * const cookies = [{ name: 'session', value: 'xyz' }];
+ * printSummary(cookies, 1);
+ * ```
  */
 function printSummary(cookies: ExportedCookie[], jwtCount: number): void {
   logger.info("\nSummary:");

src/cli/cliQueryCookies.ts

@@ -103,7 +103,6 @@ function handleOutput(results: ExportedCookie[], args: ParsedArgs): void {
 
 /**
  * Query cookies from browsers using the CLI interface
- *
  * @param cookieSpec - Cookie specification(s) to query for
  * @param browsers - List of browsers to query from
  * @param profiles - List of browser profiles to query from

src/core/browsers/CompositeCookieQueryStrategy.ts

@@ -13,7 +13,6 @@ type CookieStrategyConstructor = new () => CookieQueryStrategy;
 /**
  * A composite strategy that combines multiple cookie query strategies
  * This allows querying cookies from multiple browsers simultaneously
- *
  * @example
  */
 export class CompositeCookieQueryStrategy implements CookieQueryStrategy {
@@ -37,7 +36,6 @@ export class CompositeCookieQueryStrategy implements CookieQueryStrategy {
 
   /**
    * Queries cookies from all registered strategies
-   *
    * @param name - The name pattern to match cookies against
    * @param domain - The domain pattern to match cookies against
    * @returns A promise that resolves to an array of exported cookies from all strategies

src/core/browsers/CookieStoreQueryStrategy.ts

@@ -42,7 +42,6 @@ const ToughCookieSchema = z
 /**
  * A strategy for querying cookies from an internal cookie store
  * This class implements the CookieQueryStrategy interface and provides access to cookies stored internally
- *
  * @example
  */
 export default class CookieStoreQueryStrategy implements CookieQueryStrategy {
@@ -53,7 +52,6 @@ export default class CookieStoreQueryStrategy implements CookieQueryStrategy {
 
   /**
    * Queries cookies from the internal cookie store
-   *
    * @param name - The name of the cookie to query
    * @param domain - The domain to query cookies from
    * @returns A promise that resolves to an array of exported cookies from the internal store

src/core/browsers/chrome/ChromeApplicationSupport.ts

@@ -5,7 +5,6 @@ import { HOME } from "../../../global";
 /**
  * The path to Chrome's application support directory on macOS
  * This constant is used to locate Chrome's profile and cookie storage directories
- *
  * @example
  */
 export const chromeApplicationSupport = join(

src/core/browsers/chrome/ChromeCookieQueryStrategy.ts

@@ -50,7 +50,6 @@ function createExportedCookie(
 
 /**
  * Strategy for querying cookies from Chrome browser
- *
  * @example
  */
 export class ChromeCookieQueryStrategy implements CookieQueryStrategy {
@@ -63,7 +62,6 @@ export class ChromeCookieQueryStrategy implements CookieQueryStrategy {
 
   /**
    * Queries cookies from Chrome's cookie store
-   *
    * @param name - The name pattern to match cookies against
    * @param domain - The domain pattern to match cookies against
    * @returns A promise that resolves to an array of exported cookies

src/core/browsers/chrome/__tests__/fixtures/cookieFixtures.ts

@@ -1,15 +1,13 @@
 /**
  * Test password used for decryption tests
  * This is a real Chrome encryption password from a test environment
- *
  * @example
  */
 export const TEST_PASSWORD = "lQd+BkD+nBhODek1xUUxXw==";
 
 /**
  * Test cookie data with encrypted and expected decrypted values
  * These are real cookies from GitHub with non-sensitive values
- *
  * @example
  */
 export const TEST_COOKIES = {
@@ -48,7 +46,6 @@ export const TEST_COOKIES = {
 /**
  * Test cases for error handling scenarios
  * Each case includes the input that should trigger an error and the expected error message
- *
  * @example
  */
 export const ERROR_CASES = [

src/core/browsers/chrome/testSetup.ts

@@ -32,7 +32,6 @@ export const mockCookieData = {
 
 /**
  * Sets up a Chrome test environment with mocked dependencies
- *
  * @returns A configured ChromeCookieQueryStrategy instance
  */
 export function setupChromeTest(): ChromeCookieQueryStrategy {

src/core/browsers/firefox/FirefoxCookieQueryStrategy.ts

@@ -18,7 +18,6 @@ interface FirefoxCookieRow {
 
 /**
  * Find all Firefox cookie database files
- *
  * @returns An array of file paths to Firefox cookie databases
  */
 function findFirefoxCookieFiles(): string[] {
@@ -49,7 +48,6 @@ function findFirefoxCookieFiles(): string[] {
 
 /**
  * Strategy for querying cookies from Firefox browser
- *
  * @example
  */
 export class FirefoxCookieQueryStrategy implements CookieQueryStrategy {
@@ -60,7 +58,6 @@ export class FirefoxCookieQueryStrategy implements CookieQueryStrategy {
 
   /**
    * Queries cookies from Firefox's cookie store
-   *
    * @param name - The name pattern to match cookies against
    * @param domain - The domain pattern to match cookies against
    * @returns A promise that resolves to an array of exported cookies

src/core/browsers/getEncryptedChromeCookie.ts

@@ -30,7 +30,6 @@ interface SqlQuery {
 
 /**
  * Validates if a path is a valid, existing file
- *
  * @param path - Path to validate
  * @returns true if path is valid and file exists, false otherwise
  */
@@ -49,7 +48,6 @@ function isValidFilePath(path: unknown): path is string {
 
 /**
  * Get paths to Chrome cookie files
- *
  * @returns A promise that resolves to an array of file paths
  */
 async function getCookieFiles(): Promise<string[]> {
@@ -74,7 +72,6 @@ async function getCookieFiles(): Promise<string[]> {
 
 /**
  * Builds the SQL query for retrieving cookies
- *
  * @param name - Cookie name to search for
  * @param domain - Domain to filter by
  * @returns SQL query and parameters
@@ -91,7 +88,6 @@ function buildSqlQuery(name: string, domain: string): SqlQuery {
 
 /**
  * Processes a single cookie file to extract matching cookies
- *
  * @param cookieFile - Path to the cookie file
  * @param name - Cookie name to search for
  * @param domain - Domain to filter by
@@ -131,7 +127,6 @@ async function processCookieFile(
 
 /**
  * Retrieve encrypted cookies from Chrome's cookie store
- *
  * @param options - Options for querying Chrome cookies
  * @param options.name - The name of the cookie to retrieve
  * @param options.domain - The domain to retrieve cookies from

src/core/browsers/listChromeProfiles.ts

@@ -13,7 +13,9 @@ const consola = logger.withTag("listChromeProfiles");
 
 /**
  * Lists all Chrome profile paths that contain cookie files
- *
+ * @internal
+ * @returns An array of absolute paths to Chrome cookie files
+ * @throws {Error} If Chrome's application support directory cannot be accessed
  * @example
  * ```typescript
  * // Get all Chrome cookie file paths
@@ -30,10 +32,6 @@ const consola = logger.withTag("listChromeProfiles");
  *   console.error('Failed to access Chrome profiles:', error);
  * }
  * ```
- *
- * @returns An array of absolute paths to Chrome cookie files
- * @throws {Error} If Chrome's application support directory cannot be accessed
- * @internal
  */
 export function listChromeProfilePaths(): string[] {
   const files: string[] = sync(`./**/Cookies`, {
@@ -47,7 +45,6 @@ export function listChromeProfilePaths(): string[] {
 
 /**
  * Chrome Local State file structure
- *
  * @internal
  */
 interface ChromeLocalState {
@@ -58,7 +55,6 @@ interface ChromeLocalState {
 
 /**
  * Chrome profile information structure
- *
  * @property {string} name - The name of the profile
  * @property {number} active_time - Unix timestamp of last profile activity
  * @property {string} account_id - Unique identifier for the Chrome profile
@@ -101,7 +97,9 @@ interface ChromeProfileInfo {
 
 /**
  * Lists all Chrome profiles and their associated information
- *
+ * @internal
+ * @returns An array of Chrome profile information objects. Returns empty array if profiles cannot be read
+ * @throws {Error} If Chrome's application support directory cannot be accessed
  * @example
  * ```typescript
  * // Get all Chrome profiles
@@ -122,10 +120,6 @@ interface ChromeProfileInfo {
  *   console.log('No Chrome profiles found or error occurred');
  * }
  * ```
- *
- * @returns An array of Chrome profile information objects. Returns empty array if profiles cannot be read
- * @throws {Error} If Chrome's application support directory cannot be accessed
- * @internal
  */
 export function listChromeProfiles(): ChromeProfileInfo[] {
   try {

src/core/browsers/mock/MockCookieQueryStrategy.ts

@@ -4,7 +4,6 @@ import type { ExportedCookie } from "../../../types/ExportedCookie";
 /**
  * A mock implementation of CookieQueryStrategy for testing purposes.
  * Provides a way to simulate cookie querying behavior without a real browser.
- *
  * @example
  * // Initialize with mock cookies
  * const mockCookies = [
@@ -23,25 +22,21 @@ import type { ExportedCookie } from "../../../types/ExportedCookie";
 export default class MockCookieQueryStrategy implements CookieQueryStrategy {
   /**
    * Name identifier for the mock browser implementation
-   *
-   * @readonly
    * @internal
+   * @readonly
    */
   public readonly browserName: string = "mock";
 
   /**
    * Internal storage for mock cookie data
-   *
-   * @private
    * @internal
+   * @private
    */
   private readonly mockCookies: ExportedCookie[];
 
   /**
    * Creates a new instance of MockCookieQueryStrategy
-   *
    * @param mockCookies - Array of cookies to use as mock data. Defaults to empty array if not provided.
-   *
    * @example
    * // Initialize with single cookie
    * const strategy = new MockCookieQueryStrategy([
@@ -63,11 +58,9 @@ export default class MockCookieQueryStrategy implements CookieQueryStrategy {
 
   /**
    * Queries cookies matching the given name and domain
-   *
    * @param name - The name of the cookie to query, or "*" for all names
    * @param domain - The domain of the cookie to query, or "*" for all domains
    * @returns Promise resolving to array of matching cookies
-   *
    * @example
    * const strategy = new MockCookieQueryStrategy([
    *   { name: 'session', domain: 'example.com', value: '123' }
@@ -94,9 +87,7 @@ export default class MockCookieQueryStrategy implements CookieQueryStrategy {
 
   /**
    * Returns all mock cookies
-   *
    * @returns Promise resolving to array of all mock cookies
-   *
    * @example
    * const strategy = new MockCookieQueryStrategy([
    *   { name: 'session', domain: 'example.com', value: '123' },

src/core/cookies/CookieStore.ts

@@ -4,7 +4,6 @@ const cookieJar = new CookieJar();
 
 /**
  * Promise that resolves to a CookieJar instance for handling cookie operations
- *
  * @example
  * // Wait for cookie jar to be ready
  * const jar = await cookieJarPromise;
@@ -20,7 +19,6 @@ export const cookieJarPromise = Promise.resolve(cookieJar);
 
 /**
  * Promise that resolves to a CookieJar instance for cookie storage operations
- *
  * @example
  * // Wait for cookie store to be ready
  * const store = await cookieStorePromise;

src/core/cookies/SpecialCases.ts

@@ -2,7 +2,6 @@ import type { CookieSpec } from "../../types/CookieSpec";
 
 /**
  * Check if a cookie specification contains wildcard patterns
- *
  * @param cookieSpec - The cookie specification to check
  * @returns True if the cookie spec contains wildcard patterns, false otherwise
  * @example

src/core/cookies/comboQueryCookieSpec.ts

@@ -5,7 +5,6 @@ import { CompositeCookieQueryStrategy } from "../browsers/CompositeCookieQuerySt
 
 /**
  * Configuration options for cookie queries
- *
  * @property {CookieQueryStrategy} [strategy] - Strategy to use for querying cookies
  * @property {number} [limit] - Maximum number of cookies to return
  * @property {boolean} [removeExpired] - Whether to filter out expired cookies
@@ -18,10 +17,9 @@ interface QueryOptions {
 
 /**
  * Converts cookie expiry to consistent format
- *
+ * @internal
  * @param cookie - The cookie object to convert expiry for
  * @returns The cookie object with converted expiry
- * @internal
  */
 function convertExpiry(cookie: ExportedCookie): ExportedCookie {
   if (cookie.expiry === "Infinity") {
@@ -38,25 +36,21 @@ function convertExpiry(cookie: ExportedCookie): ExportedCookie {
  *
  * Allows querying cookies using either a single specification or multiple specifications
  * in parallel. Handles expiry dates and provides filtering options.
- *
  * @param cookieSpec - The cookie specification(s) to query
  * @param options - Optional configuration for the query operation
- *
+ * @returns A promise that resolves to an array of matching cookies
  * @example
  * // Query single cookie spec
  * const cookies = await comboQueryCookieSpec({
  *   name: "session",
  *   domain: "example.com"
  * });
- *
  * @example
  * // Query multiple specs with expired cookie removal
  * const cookies = await comboQueryCookieSpec([
  *   { name: "auth", domain: "api.example.com" },
  *   { name: "prefs", domain: "example.com" }
  * ], { removeExpired: true });
- *
- * @returns A promise that resolves to an array of matching cookies
  */
 export async function comboQueryCookieSpec(
   cookieSpec: MultiCookieSpec,