webguardx 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,658 @@
+import { z } from 'zod';
+import { Page, BrowserContext, Response } from 'playwright';
+
+declare const AuthSchema: z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+    method: z.ZodLiteral<"api-login">;
+    loginUrl: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    method: "api-login";
+    loginUrl: string;
+    payload: Record<string, string>;
+    headers?: Record<string, string> | undefined;
+}, {
+    method: "api-login";
+    loginUrl: string;
+    payload: Record<string, string>;
+    headers?: Record<string, string> | undefined;
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"form-login">;
+    loginUrl: z.ZodString;
+    fields: z.ZodArray<z.ZodObject<{
+        selector: z.ZodString;
+        value: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        selector: string;
+    }, {
+        value: string;
+        selector: string;
+    }>, "many">;
+    submitSelector: z.ZodString;
+    waitAfterLogin: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    method: "form-login";
+    loginUrl: string;
+    fields: {
+        value: string;
+        selector: string;
+    }[];
+    submitSelector: string;
+    waitAfterLogin?: string | undefined;
+}, {
+    method: "form-login";
+    loginUrl: string;
+    fields: {
+        value: string;
+        selector: string;
+    }[];
+    submitSelector: string;
+    waitAfterLogin?: string | undefined;
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"cookie">;
+    cookies: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        domain: z.ZodString;
+        path: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        path: string;
+        name: string;
+        domain: string;
+    }, {
+        value: string;
+        name: string;
+        domain: string;
+        path?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    method: "cookie";
+    cookies: {
+        value: string;
+        path: string;
+        name: string;
+        domain: string;
+    }[];
+}, {
+    method: "cookie";
+    cookies: {
+        value: string;
+        name: string;
+        domain: string;
+        path?: string | undefined;
+    }[];
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"bearer-token">;
+    token: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    method: "bearer-token";
+    token: string;
+}, {
+    method: "bearer-token";
+    token: string;
+}>, z.ZodObject<{
+    method: z.ZodLiteral<"none">;
+}, "strip", z.ZodTypeAny, {
+    method: "none";
+}, {
+    method: "none";
+}>]>;
+declare const PageSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    expectedStatus: z.ZodDefault<z.ZodNumber>;
+    skipAudits: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    name: string;
+    expectedStatus: number;
+    skipAudits?: string[] | undefined;
+}, {
+    path: string;
+    name: string;
+    expectedStatus?: number | undefined;
+    skipAudits?: string[] | undefined;
+}>;
+declare const WebguardConfigSchema: z.ZodObject<{
+    baseURL: z.ZodString;
+    pages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        expectedStatus: z.ZodDefault<z.ZodNumber>;
+        skipAudits: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        name: string;
+        expectedStatus: number;
+        skipAudits?: string[] | undefined;
+    }, {
+        path: string;
+        name: string;
+        expectedStatus?: number | undefined;
+        skipAudits?: string[] | undefined;
+    }>, "many">;
+    auth: z.ZodDefault<z.ZodDiscriminatedUnion<"method", [z.ZodObject<{
+        method: z.ZodLiteral<"api-login">;
+        loginUrl: z.ZodString;
+        payload: z.ZodRecord<z.ZodString, z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        method: "api-login";
+        loginUrl: string;
+        payload: Record<string, string>;
+        headers?: Record<string, string> | undefined;
+    }, {
+        method: "api-login";
+        loginUrl: string;
+        payload: Record<string, string>;
+        headers?: Record<string, string> | undefined;
+    }>, z.ZodObject<{
+        method: z.ZodLiteral<"form-login">;
+        loginUrl: z.ZodString;
+        fields: z.ZodArray<z.ZodObject<{
+            selector: z.ZodString;
+            value: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            selector: string;
+        }, {
+            value: string;
+            selector: string;
+        }>, "many">;
+        submitSelector: z.ZodString;
+        waitAfterLogin: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        method: "form-login";
+        loginUrl: string;
+        fields: {
+            value: string;
+            selector: string;
+        }[];
+        submitSelector: string;
+        waitAfterLogin?: string | undefined;
+    }, {
+        method: "form-login";
+        loginUrl: string;
+        fields: {
+            value: string;
+            selector: string;
+        }[];
+        submitSelector: string;
+        waitAfterLogin?: string | undefined;
+    }>, z.ZodObject<{
+        method: z.ZodLiteral<"cookie">;
+        cookies: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+            domain: z.ZodString;
+            path: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            value: string;
+            path: string;
+            name: string;
+            domain: string;
+        }, {
+            value: string;
+            name: string;
+            domain: string;
+            path?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        method: "cookie";
+        cookies: {
+            value: string;
+            path: string;
+            name: string;
+            domain: string;
+        }[];
+    }, {
+        method: "cookie";
+        cookies: {
+            value: string;
+            name: string;
+            domain: string;
+            path?: string | undefined;
+        }[];
+    }>, z.ZodObject<{
+        method: z.ZodLiteral<"bearer-token">;
+        token: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        method: "bearer-token";
+        token: string;
+    }, {
+        method: "bearer-token";
+        token: string;
+    }>, z.ZodObject<{
+        method: z.ZodLiteral<"none">;
+    }, "strip", z.ZodTypeAny, {
+        method: "none";
+    }, {
+        method: "none";
+    }>]>>;
+    audits: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    customAudits: z.ZodDefault<z.ZodArray<z.ZodAny, "many">>;
+    plugins: z.ZodDefault<z.ZodArray<z.ZodAny, "many">>;
+    wcagTags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    lighthouseThresholds: z.ZodDefault<z.ZodObject<{
+        performance: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        accessibility: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        bestPractices: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        seo: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        performance?: number | undefined;
+        accessibility?: number | undefined;
+        bestPractices?: number | undefined;
+        seo?: number | undefined;
+    }, {
+        performance?: number | undefined;
+        accessibility?: number | undefined;
+        bestPractices?: number | undefined;
+        seo?: number | undefined;
+    }>>;
+    retry: z.ZodDefault<z.ZodObject<{
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        delayMs: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxRetries: number;
+        delayMs: number;
+    }, {
+        maxRetries?: number | undefined;
+        delayMs?: number | undefined;
+    }>>;
+    runner: z.ZodDefault<z.ZodObject<{
+        concurrency: z.ZodDefault<z.ZodNumber>;
+        failFast: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        concurrency: number;
+        failFast: boolean;
+    }, {
+        concurrency?: number | undefined;
+        failFast?: boolean | undefined;
+    }>>;
+    browser: z.ZodDefault<z.ZodObject<{
+        headless: z.ZodDefault<z.ZodBoolean>;
+        timeout: z.ZodDefault<z.ZodNumber>;
+        viewport: z.ZodDefault<z.ZodObject<{
+            width: z.ZodDefault<z.ZodNumber>;
+            height: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        headless: boolean;
+        timeout: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    }, {
+        headless?: boolean | undefined;
+        timeout?: number | undefined;
+        viewport?: {
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+    }>>;
+    output: z.ZodDefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        formats: z.ZodDefault<z.ZodArray<z.ZodEnum<["terminal", "html", "json", "junit"]>, "many">>;
+        screenshots: z.ZodDefault<z.ZodBoolean>;
+        screenshotOnFailOnly: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        formats: ("terminal" | "html" | "json" | "junit")[];
+        screenshots: boolean;
+        screenshotOnFailOnly: boolean;
+    }, {
+        dir?: string | undefined;
+        formats?: ("terminal" | "html" | "json" | "junit")[] | undefined;
+        screenshots?: boolean | undefined;
+        screenshotOnFailOnly?: boolean | undefined;
+    }>>;
+    baseline: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        updateOnPass: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        updateOnPass: boolean;
+    }, {
+        enabled?: boolean | undefined;
+        updateOnPass?: boolean | undefined;
+    }>>;
+    notifications: z.ZodDefault<z.ZodArray<z.ZodAny, "many">>;
+}, "strip", z.ZodTypeAny, {
+    baseURL: string;
+    pages: {
+        path: string;
+        name: string;
+        expectedStatus: number;
+        skipAudits?: string[] | undefined;
+    }[];
+    auth: {
+        method: "api-login";
+        loginUrl: string;
+        payload: Record<string, string>;
+        headers?: Record<string, string> | undefined;
+    } | {
+        method: "form-login";
+        loginUrl: string;
+        fields: {
+            value: string;
+            selector: string;
+        }[];
+        submitSelector: string;
+        waitAfterLogin?: string | undefined;
+    } | {
+        method: "cookie";
+        cookies: {
+            value: string;
+            path: string;
+            name: string;
+            domain: string;
+        }[];
+    } | {
+        method: "bearer-token";
+        token: string;
+    } | {
+        method: "none";
+    };
+    audits: Record<string, boolean>;
+    customAudits: any[];
+    plugins: any[];
+    wcagTags: string[];
+    lighthouseThresholds: {
+        performance?: number | undefined;
+        accessibility?: number | undefined;
+        bestPractices?: number | undefined;
+        seo?: number | undefined;
+    };
+    retry: {
+        maxRetries: number;
+        delayMs: number;
+    };
+    runner: {
+        concurrency: number;
+        failFast: boolean;
+    };
+    browser: {
+        headless: boolean;
+        timeout: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    };
+    output: {
+        dir: string;
+        formats: ("terminal" | "html" | "json" | "junit")[];
+        screenshots: boolean;
+        screenshotOnFailOnly: boolean;
+    };
+    baseline: {
+        enabled: boolean;
+        updateOnPass: boolean;
+    };
+    notifications: any[];
+}, {
+    baseURL: string;
+    pages: {
+        path: string;
+        name: string;
+        expectedStatus?: number | undefined;
+        skipAudits?: string[] | undefined;
+    }[];
+    auth?: {
+        method: "api-login";
+        loginUrl: string;
+        payload: Record<string, string>;
+        headers?: Record<string, string> | undefined;
+    } | {
+        method: "form-login";
+        loginUrl: string;
+        fields: {
+            value: string;
+            selector: string;
+        }[];
+        submitSelector: string;
+        waitAfterLogin?: string | undefined;
+    } | {
+        method: "cookie";
+        cookies: {
+            value: string;
+            name: string;
+            domain: string;
+            path?: string | undefined;
+        }[];
+    } | {
+        method: "bearer-token";
+        token: string;
+    } | {
+        method: "none";
+    } | undefined;
+    audits?: Record<string, boolean> | undefined;
+    customAudits?: any[] | undefined;
+    plugins?: any[] | undefined;
+    wcagTags?: string[] | undefined;
+    lighthouseThresholds?: {
+        performance?: number | undefined;
+        accessibility?: number | undefined;
+        bestPractices?: number | undefined;
+        seo?: number | undefined;
+    } | undefined;
+    retry?: {
+        maxRetries?: number | undefined;
+        delayMs?: number | undefined;
+    } | undefined;
+    runner?: {
+        concurrency?: number | undefined;
+        failFast?: boolean | undefined;
+    } | undefined;
+    browser?: {
+        headless?: boolean | undefined;
+        timeout?: number | undefined;
+        viewport?: {
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+    } | undefined;
+    output?: {
+        dir?: string | undefined;
+        formats?: ("terminal" | "html" | "json" | "junit")[] | undefined;
+        screenshots?: boolean | undefined;
+        screenshotOnFailOnly?: boolean | undefined;
+    } | undefined;
+    baseline?: {
+        enabled?: boolean | undefined;
+        updateOnPass?: boolean | undefined;
+    } | undefined;
+    notifications?: any[] | undefined;
+}>;
+type WebguardConfig = z.infer<typeof WebguardConfigSchema>;
+type PageEntry = z.infer<typeof PageSchema>;
+type AuthConfig = z.infer<typeof AuthSchema>;
+
+type WebguardConfigInput = z.input<typeof WebguardConfigSchema>;
+declare function defineConfig(config: WebguardConfigInput): WebguardConfig;
+
+declare function loadConfig(configPath?: string): Promise<WebguardConfig>;
+
+type AuditSeverity = "pass" | "warning" | "fail" | "skip";
+interface AuditResult {
+    audit: string;
+    page: string;
+    passed: boolean;
+    severity: AuditSeverity;
+    message: string;
+    details?: unknown;
+    duration?: number;
+}
+interface PageResult {
+    page: string;
+    path: string;
+    url: string;
+    audits: AuditResult[];
+    screenshotPath?: string;
+    duration: number;
+}
+interface RunResult {
+    timestamp: string;
+    config: {
+        baseURL: string;
+        totalPages: number;
+        auditsEnabled: string[];
+    };
+    pages: PageResult[];
+    summary: {
+        totalAudits: number;
+        passed: number;
+        failed: number;
+        warnings: number;
+        skipped: number;
+        duration: number;
+    };
+}
+
+interface RunOptions {
+    headed?: boolean;
+    pagesFilter?: string[];
+    auditsFilter?: string[];
+}
+declare function run(config: WebguardConfig, options?: RunOptions): Promise<RunResult>;
+
+interface AuditContext {
+    page: Page;
+    browserContext: BrowserContext;
+    pageEntry: PageEntry;
+    config: WebguardConfig;
+    runDir: string;
+    navigationResponse: Response | null;
+    consoleMessages: Array<{
+        type: string;
+        text: string;
+    }>;
+}
+interface Audit {
+    name: string;
+    description: string;
+    run(ctx: AuditContext): Promise<AuditResult>;
+}
+
+interface WebguardPlugin {
+    name: string;
+    audits?: Audit[];
+    reporters?: Reporter[];
+    hooks?: Partial<LifecycleHooks>;
+}
+interface Reporter {
+    name: string;
+    run(result: RunResult, runDir: string, config: WebguardConfig): Promise<void> | void;
+}
+interface LifecycleHooks {
+    beforeAll(ctx: {
+        config: WebguardConfig;
+        browserContext: BrowserContext;
+    }): Promise<void> | void;
+    afterAll(ctx: {
+        config: WebguardConfig;
+        result: RunResult;
+    }): Promise<void> | void;
+    beforePage(ctx: {
+        config: WebguardConfig;
+        pageEntry: PageEntry;
+        page: Page;
+    }): Promise<void> | void;
+    afterPage(ctx: {
+        config: WebguardConfig;
+        pageEntry: PageEntry;
+        pageResult: PageResult;
+    }): Promise<void> | void;
+    beforeAudit(ctx: {
+        audit: Audit;
+        auditContext: AuditContext;
+    }): Promise<void> | void;
+    afterAudit(ctx: {
+        audit: Audit;
+        result: AuditResult;
+    }): Promise<void> | void;
+}
+
+declare class PluginRegistry {
+    private plugins;
+    register(plugin: WebguardPlugin): void;
+    getPluginAudits(): Audit[];
+    getPluginReporters(): Reporter[];
+    runHook<K extends keyof LifecycleHooks>(hookName: K, ctx: Parameters<LifecycleHooks[K]>[0]): Promise<void>;
+}
+
+declare function loadPlugins(pluginEntries: Array<WebguardPlugin | string>): Promise<WebguardPlugin[]>;
+
+interface NotificationChannel {
+    name: string;
+    send(result: RunResult, config: WebguardConfig): Promise<void>;
+}
+
+interface WebhookOptions {
+    method?: "POST" | "PUT";
+    headers?: Record<string, string>;
+    onlyOnFailure?: boolean;
+}
+declare function createWebhookNotifier(url: string, options?: WebhookOptions): NotificationChannel;
+
+interface SlackOptions {
+    channel?: string;
+    onlyOnFailure?: boolean;
+}
+declare function createSlackNotifier(webhookUrl: string, options?: SlackOptions): NotificationChannel;
+
+declare function sendNotifications(channels: NotificationChannel[], result: RunResult, config: WebguardConfig): Promise<void>;
+
+interface BaselineComparison {
+    baselineTimestamp: string;
+    currentTimestamp: string;
+    changes: AuditChange[];
+    summary: {
+        regressions: number;
+        improvements: number;
+        unchanged: number;
+        newAudits: number;
+        removedAudits: number;
+    };
+}
+interface AuditChange {
+    page: string;
+    audit: string;
+    type: "regression" | "improvement" | "unchanged" | "new" | "removed";
+    baseline?: {
+        severity: string;
+        message: string;
+    };
+    current?: {
+        severity: string;
+        message: string;
+    };
+}
+
+declare function saveBaseline(result: RunResult, outputDir: string): void;
+declare function loadBaseline(outputDir: string): RunResult | null;
+
+declare function compareRuns(baseline: RunResult, current: RunResult): BaselineComparison;
+
+declare const HttpStatusAudit: Audit;
+
+declare const ContentVisibilityAudit: Audit;
+
+declare const AccessibilityAudit: Audit;
+
+declare const LighthouseAudit: Audit;
+
+declare const BrokenLinksAudit: Audit;
+
+declare const ConsoleErrorsAudit: Audit;
+
+export { AccessibilityAudit, type Audit, type AuditChange, type AuditContext, type AuditResult, type AuditSeverity, type AuthConfig, type BaselineComparison, BrokenLinksAudit, ConsoleErrorsAudit, ContentVisibilityAudit, HttpStatusAudit, type LifecycleHooks, LighthouseAudit, type NotificationChannel, type PageEntry, type PageResult, PluginRegistry, type Reporter, type RunOptions, type RunResult, type WebguardConfig, type WebguardPlugin, compareRuns, createSlackNotifier, createWebhookNotifier, defineConfig, loadBaseline, loadConfig, loadPlugins, run, saveBaseline, sendNotifications };