audit0 0.1.0

package/dist/engine/navigation.mjs

@@ -0,0 +1,427 @@
+import { writeFile } from "node:fs/promises";
+import { startNavigationRequestCapture } from "./navigation-requests.mjs";
+import { sanitizeUrl } from "./page-diagnostics.mjs";
+import { defaultSettings } from "./settings.mjs";
+// Self-contained so the same predicates run in Playwright waits and the in-page sampler.
+export function inspectState(spec) {
+    const visible = (el, minSize = 3) => {
+        if (!el.checkVisibility({
+            opacityProperty: true,
+            visibilityProperty: true,
+            contentVisibilityAuto: true,
+        }))
+            return false;
+        const rect = el.getBoundingClientRect();
+        return (rect.width > minSize &&
+            rect.height > minSize &&
+            rect.bottom > 0 &&
+            rect.right > 0 &&
+            rect.top < innerHeight &&
+            rect.left < innerWidth);
+    };
+    const matches = (root, rule) => {
+        const pattern = rule.pattern
+            ? typeof rule.pattern === "string"
+                ? new RegExp(rule.pattern, "i")
+                : new RegExp(rule.pattern.source, rule.pattern.flags)
+            : null;
+        return [...root.querySelectorAll(rule.selector)].filter((el) => {
+            if (!visible(el))
+                return false;
+            const text = el.innerText?.trim().slice(0, 3000) || el.getAttribute("aria-label") || "";
+            if (rule.text !== undefined && text !== rule.text)
+                return false;
+            if (pattern && !pattern.test(text))
+                return false;
+            return (rule.contains || []).every((child) => matches(el, child).length >= (child.min || 1));
+        });
+    };
+    const counts = {};
+    for (const [name, rule] of Object.entries(spec.markers))
+        counts[name] = matches(document, rule).length;
+    const route = location.pathname === spec.path;
+    const has = (name) => counts[name] >= (spec.markers[name].min || 1);
+    const primary = route && spec.primary.every(has);
+    const complete = primary && (spec.complete || []).every(has);
+    const shell = route && (spec.shell || []).every(has);
+    const activeMilestones = (spec.milestones || [])
+        .filter((milestone) => milestone.markers.every(has))
+        .map((milestone) => milestone.id);
+    const fallbackCount = spec.fallback ? matches(document, spec.fallback).length : null;
+    const indicators = (spec.feedbackIndicators || []).flatMap((selector) => [...document.querySelectorAll(selector)]
+        .filter((el) => visible(el, 0))
+        .map((el) => {
+        const rect = el.getBoundingClientRect();
+        return { selector, x: rect.x, width: rect.width };
+    }));
+    return {
+        path: location.pathname,
+        route,
+        shell,
+        primary,
+        complete,
+        activeMilestones,
+        counts,
+        fallbackCount,
+        indicators,
+        state: !route
+            ? "previous-route"
+            : complete
+                ? "useful-complete"
+                : primary
+                    ? "useful-partial"
+                    : shell
+                        ? "shell-only"
+                        : "destination-not-ready",
+    };
+}
+export async function waitForContent(page, spec, timeout = 20000) {
+    const deadline = performance.now() + timeout;
+    while (performance.now() < deadline) {
+        try {
+            if ((await page.evaluate(inspectState, spec)).primary)
+                return;
+        }
+        catch (error) {
+            if (!error.message.includes("Execution context was destroyed"))
+                throw error;
+        }
+        await page.waitForTimeout(100);
+    }
+    throw new Error(`Useful content not observed on ${spec.path} within ${timeout}ms`);
+}
+function monitor(spec, inspect, binding, autoStart) {
+    if (window !== window.top)
+        return;
+    const clock = () => performance.timeOrigin + performance.now();
+    const samples = [];
+    let active = autoStart;
+    let previous = "";
+    let lastStored = 0;
+    let frame;
+    let startEpochMs = null;
+    let baseline = autoStart ? null : inspect(spec);
+    function sample() {
+        if (!active)
+            return;
+        const state = inspect(spec);
+        const feedbackReasons = [];
+        if (state.shell)
+            feedbackReasons.push("destination-shell");
+        else if (state.primary)
+            feedbackReasons.push("useful-content");
+        if (state.route && state.fallbackCount > (baseline?.fallbackCount || 0))
+            feedbackReasons.push("new-destination-fallback");
+        if (baseline &&
+            state.indicators.some((indicator, i) => {
+                const before = baseline.indicators[i];
+                return (!before ||
+                    indicator.selector !== before.selector ||
+                    Math.abs(indicator.x - before.x) >= 1 ||
+                    Math.abs(indicator.width - before.width) >= 1);
+            }))
+            feedbackReasons.push("navigation-indicator-moved");
+        state.feedback = feedbackReasons.length > 0;
+        state.feedbackReasons = feedbackReasons;
+        const epochMs = clock();
+        const signature = JSON.stringify(state);
+        if (signature !== previous || epochMs - lastStored >= 100) {
+            const observation = { epochMs, ...state };
+            samples.push(observation);
+            if (signature !== previous)
+                window[binding]({ type: "samples", samples: [observation] });
+            previous = signature;
+            lastStored = epochMs;
+        }
+        if (samples.length < 1000)
+            frame = requestAnimationFrame(sample);
+    }
+    function click(event) {
+        const link = event.target.closest?.("a[href]");
+        if (!link || new URL(link.href).pathname !== spec.path || active)
+            return;
+        startEpochMs = performance.timeOrigin + event.timeStamp;
+        baseline = inspect(spec);
+        active = true;
+        window[binding]({
+            type: "click",
+            epochMs: startEpochMs,
+            handlerEpochMs: clock(),
+            timeOrigin: performance.timeOrigin,
+            initialSample: {
+                epochMs: clock(),
+                ...baseline,
+                preClickBaseline: true,
+                feedback: false,
+                feedbackReasons: [],
+            },
+        });
+        sample();
+    }
+    document.addEventListener("click", click, { capture: true });
+    const flush = () => window[binding]({ type: "samples", samples });
+    window.addEventListener("pagehide", flush, { once: true });
+    window.__auditNavigation = {
+        finish() {
+            active = false;
+            cancelAnimationFrame(frame);
+            document.removeEventListener("click", click, { capture: true });
+            window.removeEventListener("pagehide", flush);
+            return {
+                samples,
+                timeOrigin: performance.timeOrigin,
+                collectedEpochMs: clock(),
+                finalState: inspect(spec),
+            };
+        },
+    };
+    if (autoStart)
+        frame = requestAnimationFrame(sample);
+}
+export function summarizeNavigation(samples, clickEpochMs, observationMs = Infinity, milestones = []) {
+    const uniqueSamples = [...new Map(samples.map((sample) => [sample.epochMs, sample])).values()];
+    const timeline = uniqueSamples
+        .filter((sample) => sample.epochMs >= clickEpochMs && sample.epochMs <= clickEpochMs + observationMs)
+        .sort((a, b) => a.epochMs - b.epochMs)
+        .map(({ epochMs, ...sample }) => ({ atMs: epochMs - clickEpochMs, ...sample }));
+    const first = (key) => timeline.find((sample) => sample[key])?.atMs ?? null;
+    const preClickBaseline = timeline.find((sample) => sample.preClickBaseline);
+    const milestoneTimings = Object.fromEntries(milestones.map((milestone) => [
+        milestone.id,
+        preClickBaseline?.activeMilestones?.includes(milestone.id)
+            ? 0
+            : (timeline.find((sample) => sample.activeMilestones?.includes(milestone.id))?.atMs ??
+                null),
+    ]));
+    const stateAt = (cutoff) => {
+        const before = timeline.filter((sample) => sample.atMs <= cutoff).at(-1);
+        const after = timeline.find((sample) => sample.atMs > cutoff);
+        return {
+            requestedMs: cutoff,
+            lastObservedMs: before?.atMs ?? null,
+            nextObservedMs: after?.atMs ?? null,
+            state: before?.state ?? "not-observed",
+            activeMilestones: before?.activeMilestones ?? [],
+            counts: before?.counts ?? {},
+        };
+    };
+    return {
+        clickToFeedbackMs: first("feedback"),
+        firstFeedbackReasons: timeline.find((sample) => sample.feedback)?.feedbackReasons ?? [],
+        clickToUrlMs: first("route"),
+        clickToShellMs: first("shell"),
+        clickToUsefulMs: first("primary"),
+        clickToCompleteMs: first("complete"),
+        milestoneTimings,
+        checkpoints: [50, 100, 500, 1000, 2000, 3000].map(stateAt),
+        timeline,
+    };
+}
+export async function hoverBeforeClick(target, settings = defaultSettings) {
+    await target.scrollIntoViewIfNeeded({ timeout: 10000 });
+    await target.hover({ timeout: 10000 });
+    await target.page().waitForTimeout(settings.preClickHoverMs);
+}
+export async function waitForClientReadyLink(target, timeout = 20000) {
+    const element = await target.elementHandle({ timeout });
+    if (!element)
+        throw new Error("Navigation link was not available for client-readiness detection");
+    await target.page().waitForFunction((link) => {
+        const propsKey = Object.keys(link).find((key) => key.startsWith("__reactProps$"));
+        return Boolean(propsKey && typeof link[propsKey]?.onClick === "function");
+    }, element, { timeout });
+}
+/**
+ * @param {import('@playwright/test').Page} page
+ * @param {object} spec
+ * @param {object} [options]
+ * @param {string} [options.directory]
+ * @param {number} [options.observeMs]
+ * @param {boolean} [options.requireClientReady]
+ * @param {object} [options.requestCapture]
+ * @param {object} [options.settings]
+ */
+export async function measureNavigation(page, spec, { directory, observeMs = 5000, requireClientReady = false, requestCapture: suppliedRequestCapture, settings = defaultSettings, } = {}) {
+    const binding = `auditClick${Date.now()}`;
+    let clickEvent;
+    let resolveClick;
+    let completionObserved = false;
+    let resolveCompletion;
+    const clickPromise = new Promise((resolve) => {
+        resolveClick = resolve;
+    });
+    const completionPromise = new Promise((resolve) => {
+        resolveCompletion = resolve;
+    });
+    const previousSamples = [];
+    const observeCompletion = (sample) => {
+        if (!completionObserved &&
+            clickEvent &&
+            sample.complete &&
+            sample.epochMs >= clickEvent.epochMs) {
+            completionObserved = true;
+            resolveCompletion(sample);
+        }
+    };
+    await page.exposeBinding(binding, (_, event) => {
+        if (event.type === "click") {
+            clickEvent = event;
+            previousSamples.push(event.initialSample);
+            observeCompletion(event.initialSample);
+            resolveClick(event);
+        }
+        else {
+            previousSamples.push(...event.samples);
+            for (const sample of event.samples)
+                observeCompletion(sample);
+        }
+    });
+    const session = await page.context().newCDPSession(page);
+    const requestCapture = suppliedRequestCapture ??
+        (await startNavigationRequestCapture(page, new URL(spec.path, page.url()).href));
+    let requests = [];
+    await session.send("Page.enable");
+    const source = `(${monitor.toString()})(${JSON.stringify(spec)}, (${inspectState.toString()}), ${JSON.stringify(binding)}, true)`;
+    const { identifier } = await session.send("Page.addScriptToEvaluateOnNewDocument", { source });
+    await page.evaluate(`(${monitor.toString()})(${JSON.stringify(spec)}, (${inspectState.toString()}), ${JSON.stringify(binding)}, false)`);
+    const frames = [];
+    const pendingWrites = [];
+    const collectionErrors = [];
+    const captureFrames = Boolean(directory);
+    let frameCaptureStarted = false;
+    let droppedFrames = 0;
+    const onFrame = (event) => {
+        void session.send("Page.screencastFrameAck", { sessionId: event.sessionId }).catch(() => { });
+        if (!event.metadata.timestamp)
+            return;
+        const epochMs = event.metadata.timestamp * 1000;
+        if (!clickEvent && frames.length)
+            return;
+        if (frames.length >= 100) {
+            droppedFrames++;
+            return;
+        }
+        if (frames.length && epochMs - frames.at(-1).epochMs < 100)
+            return;
+        const name = `frame-${String(frames.length).padStart(3, "0")}.jpg`;
+        frames.push({ file: name, epochMs });
+        pendingWrites.push(writeFile(`${directory}/${name}`, Buffer.from(event.data, "base64")).catch(() => {
+            collectionErrors.push(`Could not write ${name}`);
+        }));
+    };
+    const stopFrameCapture = async () => {
+        if (!frameCaptureStarted)
+            return;
+        await session
+            .send("Page.stopScreencast")
+            .catch(() => collectionErrors.push("Could not stop screencast"));
+        session.off("Page.screencastFrame", onFrame);
+        frameCaptureStarted = false;
+        await Promise.all(pendingWrites);
+    };
+    try {
+        if (captureFrames) {
+            session.on("Page.screencastFrame", onFrame);
+            await session.send("Page.startScreencast", {
+                format: "jpeg",
+                quality: 65,
+                maxWidth: 1440,
+                maxHeight: 1000,
+                everyNthFrame: 1,
+            });
+            frameCaptureStarted = true;
+        }
+        const target = page
+            .locator(`a[href=${JSON.stringify(spec.path)}]`)
+            .filter({ visible: true })
+            .first();
+        const href = await target.getAttribute("href", { timeout: 10000 });
+        if (new URL(href, page.url()).origin !== new URL(page.url()).origin)
+            throw new Error("Cross-origin navigation refused");
+        let clientReadyWaitMs = null;
+        if (requireClientReady) {
+            const clientReadyStartedAt = performance.now();
+            await waitForClientReadyLink(target);
+            clientReadyWaitMs = performance.now() - clientReadyStartedAt;
+        }
+        await hoverBeforeClick(target, settings);
+        await target.click({ timeout: 10000, noWaitAfter: true });
+        let clickTimeout;
+        try {
+            await Promise.race([
+                clickPromise,
+                new Promise((_, reject) => {
+                    clickTimeout = setTimeout(() => reject(new Error("Expected click was not observed")), 2000);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(clickTimeout);
+        }
+        if (!clickEvent)
+            throw new Error("No click timestamp recorded");
+        let observationTimer;
+        const endReason = await Promise.race([
+            completionPromise.then(() => "complete"),
+            new Promise((resolve) => {
+                observationTimer = setTimeout(() => resolve("timeout"), Math.max(0, clickEvent.epochMs + observeMs - Date.now()));
+            }),
+        ]);
+        clearTimeout(observationTimer);
+        let snapshot;
+        try {
+            snapshot = await page.evaluate(() => window.__auditNavigation?.finish());
+        }
+        catch {
+            collectionErrors.push("Document changed during final collection; retained outgoing samples only");
+        }
+        if (!snapshot)
+            collectionErrors.push("Final navigation observer unavailable");
+        const summary = summarizeNavigation([...previousSamples, ...(snapshot?.samples || [])], clickEvent.epochMs, observeMs, spec.milestones);
+        try {
+            requests = await requestCapture.finish(clickEvent.epochMs);
+        }
+        catch {
+            collectionErrors.push("Could not finish navigation request collection");
+        }
+        await stopFrameCapture();
+        return {
+            ...summary,
+            type: !snapshot
+                ? "unknown"
+                : snapshot.timeOrigin === clickEvent.timeOrigin
+                    ? "same-document"
+                    : "full-document",
+            observationMs: observeMs,
+            endReason,
+            preClickHoverMs: settings.preClickHoverMs,
+            clientReadyWaitMs,
+            collectedAtMs: snapshot ? snapshot.collectedEpochMs - clickEvent.epochMs : null,
+            finalState: snapshot?.finalState ?? null,
+            collectionErrors,
+            droppedFrames,
+            clickEpochMs: clickEvent.epochMs,
+            clickHandlerDelayMs: clickEvent.handlerEpochMs - clickEvent.epochMs,
+            finalUrl: sanitizeUrl(page.url()),
+            requests,
+            frames: frames.map(({ epochMs, ...frame }) => ({
+                ...frame,
+                atMs: epochMs - clickEvent.epochMs,
+            })),
+        };
+    }
+    finally {
+        await stopFrameCapture();
+        await Promise.all(pendingWrites);
+        await requestCapture
+            .dispose()
+            .catch(() => collectionErrors.push("Could not dispose navigation request collection"));
+        await session
+            .send("Page.removeScriptToEvaluateOnNewDocument", { identifier })
+            .catch(() => collectionErrors.push("Could not remove navigation observer"));
+        await page.evaluate(() => window.__auditNavigation?.finish()).catch(() => { });
+        await session
+            .detach()
+            .catch(() => collectionErrors.push("Could not detach navigation CDP session"));
+    }
+}

package/dist/engine/page-diagnostics.d.mts

@@ -0,0 +1,18 @@
+export declare function sanitizeUrl(raw: any): string;
+export declare function responseTiming(timing: any): {
+    ttfbMs: null;
+    source: string;
+} | {
+    ttfbMs: number;
+    source: string;
+};
+export declare function classifyResourceTiming(entry: any, documentUrl: any, cdpType: any): {
+    timingAvailability: string;
+    ttfbMs: number | null;
+    renderBlockingScript: boolean;
+};
+export declare function classifyFontFace(face: any): any;
+export declare function startPageDiagnostics(page: any): Promise<{
+    finish(): Promise<any>;
+    dispose: () => Promise<any>;
+}>;