apex-auditor 0.3.0 → 0.3.3

package/dist/measure-runner.js

@@ -0,0 +1,447 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { launch as launchChrome } from "chrome-launcher";
+import { CdpClient } from "./cdp-client.js";
+const DEFAULT_NAVIGATION_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_PARALLEL = 4;
+const DEFAULT_ARTIFACTS_DIR = ".apex-auditor/measure";
+const CHROME_FLAGS = [
+    "--headless=new",
+    "--disable-gpu",
+    "--no-sandbox",
+    "--disable-dev-shm-usage",
+    "--disable-extensions",
+    "--disable-default-apps",
+    "--no-first-run",
+    "--no-default-browser-check",
+];
+const MOBILE_METRICS = { mobile: true, width: 412, height: 823, deviceScaleFactor: 2 };
+const DESKTOP_METRICS = { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1 };
+const MOBILE_UA = "Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36";
+function buildUrl({ baseUrl, path, query }) {
+    const cleanBase = baseUrl.replace(/\/$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const queryPart = query && query.length > 0 ? query : "";
+    return `${cleanBase}${cleanPath}${queryPart}`;
+}
+function slugify(value) {
+    const safe = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return safe.length > 0 ? safe : "page";
+}
+function buildArtifactBaseName(task) {
+    const hash = createHash("sha1").update(`${task.url}::${task.device}`).digest("hex").slice(0, 10);
+    const pathPart = slugify(task.path);
+    return `${pathPart}-${task.device}-${hash}`;
+}
+function resolveParallelCount(params) {
+    const requested = params.requested;
+    if (requested !== undefined) {
+        return Math.max(1, Math.min(DEFAULT_MAX_PARALLEL, Math.min(params.taskCount, requested)));
+    }
+    return Math.max(1, Math.min(DEFAULT_MAX_PARALLEL, params.taskCount));
+}
+async function createChromeSession() {
+    const userDataDir = await mkdtemp(join(tmpdir(), "apex-auditor-measure-chrome-"));
+    const chrome = await launchChrome({ chromeFlags: [...CHROME_FLAGS, `--user-data-dir=${userDataDir}`] });
+    return {
+        port: chrome.port,
+        close: async () => {
+            try {
+                await chrome.kill();
+                await rm(userDataDir, { recursive: true, force: true });
+            }
+            catch {
+                return;
+            }
+        },
+    };
+}
+async function fetchJsonVersion(port) {
+    const url = `http://127.0.0.1:${port}/json/version`;
+    return new Promise((resolve, reject) => {
+        const request = httpRequest(url, (response) => {
+            const statusCode = response.statusCode ?? 0;
+            if (statusCode < 200 || statusCode >= 300) {
+                response.resume();
+                reject(new Error(`CDP /json/version returned HTTP ${statusCode}`));
+                return;
+            }
+            const chunks = [];
+            response.on("data", (chunk) => {
+                chunks.push(chunk);
+            });
+            response.on("end", () => {
+                const raw = Buffer.concat(chunks).toString("utf8");
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object") {
+                    reject(new Error("Invalid /json/version response"));
+                    return;
+                }
+                const record = parsed;
+                if (typeof record.webSocketDebuggerUrl !== "string" || record.webSocketDebuggerUrl.length === 0) {
+                    reject(new Error("Missing webSocketDebuggerUrl in /json/version"));
+                    return;
+                }
+                resolve({ webSocketDebuggerUrl: record.webSocketDebuggerUrl });
+            });
+        });
+        request.on("error", reject);
+        request.end();
+    });
+}
+function buildTasks(config) {
+    const tasks = [];
+    for (const page of config.pages) {
+        for (const device of page.devices) {
+            const url = buildUrl({ baseUrl: config.baseUrl, path: page.path, query: config.query });
+            tasks.push({ url, path: page.path, label: page.label, device });
+        }
+    }
+    return tasks;
+}
+function buildMeasureScript() {
+    return `(() => {
+  const state = {
+    cls: 0,
+    lcp: undefined,
+    inp: undefined,
+  };
+  const clsObserver = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      const e = entry;
+      if (e.hadRecentInput) {
+        continue;
+      }
+      state.cls += e.value;
+    }
+  });
+  try { clsObserver.observe({ type: 'layout-shift', buffered: true }); } catch {}
+  const lcpObserver = new PerformanceObserver((list) => {
+    const entries = list.getEntries();
+    const last = entries[entries.length - 1];
+    if (last) {
+      state.lcp = last.startTime;
+    }
+  });
+  try { lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true }); } catch {}
+  const inpObserver = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      if (typeof entry.interactionId !== 'number') {
+        continue;
+      }
+      const duration = entry.duration;
+      if (typeof duration === 'number') {
+        state.inp = state.inp === undefined ? duration : Math.max(state.inp, duration);
+      }
+    }
+  });
+  try { inpObserver.observe({ type: 'event', buffered: true, durationThreshold: 40 }); } catch {}
+  (globalThis).__apexMeasure = state;
+})()`;
+}
+function applyDeviceEmulation(client, device, sessionId) {
+    if (device === "mobile") {
+        return Promise.all([
+            client.send("Emulation.setDeviceMetricsOverride", MOBILE_METRICS, sessionId),
+            client.send("Emulation.setUserAgentOverride", { userAgent: MOBILE_UA }, sessionId),
+        ]);
+    }
+    return client.send("Emulation.setDeviceMetricsOverride", DESKTOP_METRICS, sessionId);
+}
+function recordLogEvents(client, sessionId, bucket) {
+    const offException = client.onEvent("Runtime.exceptionThrown", sessionId, (payload) => {
+        const text = typeof payload === "object" && payload !== null ? JSON.stringify(payload) : String(payload);
+        bucket.push(`exception: ${text}`);
+    });
+    const offConsole = client.onEvent("Runtime.consoleAPICalled", sessionId, (payload) => {
+        const text = typeof payload === "object" && payload !== null ? JSON.stringify(payload) : String(payload);
+        if (text.toLowerCase().includes("error")) {
+            bucket.push(`console: ${text}`);
+        }
+    });
+    const offLog = client.onEvent("Log.entryAdded", sessionId, (payload) => {
+        const record = payload;
+        const entry = record.entry;
+        const level = typeof entry?.level === "string" ? entry.level : "";
+        const text = typeof entry?.text === "string" ? entry.text : "";
+        if (level === "error" && text.length > 0) {
+            bucket.push(text);
+        }
+    });
+    return () => {
+        offException();
+        offConsole();
+        offLog();
+    };
+}
+async function captureScreenshot(client, task, sessionId, artifactsDir) {
+    try {
+        const screenshot = await client.send("Page.captureScreenshot", { format: "png" }, sessionId);
+        const data = typeof screenshot.data === "string" ? screenshot.data : undefined;
+        if (!data) {
+            return undefined;
+        }
+        const baseName = buildArtifactBaseName(task);
+        const screenshotPath = resolve(artifactsDir, `${baseName}.png`);
+        await writeFile(screenshotPath, Buffer.from(data, "base64"));
+        return screenshotPath;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseMeasureResult(valueUnknown) {
+    const value = valueUnknown && typeof valueUnknown === "object" ? valueUnknown : {};
+    const ttfbMs = typeof value.navigation?.responseStart === "number" ? value.navigation.responseStart : undefined;
+    const domContentLoadedMs = typeof value.navigation?.domContentLoadedEventEnd === "number" ? value.navigation.domContentLoadedEventEnd : undefined;
+    const loadMs = typeof value.navigation?.loadEventEnd === "number" ? value.navigation.loadEventEnd : undefined;
+    const lcpMs = typeof value.vitals?.lcpMs === "number" ? value.vitals.lcpMs : undefined;
+    const cls = typeof value.vitals?.cls === "number" ? value.vitals.cls : undefined;
+    const inpMs = typeof value.vitals?.inpMs === "number" ? value.vitals.inpMs : undefined;
+    const longTasks = {
+        count: typeof value.longTasks?.count === "number" ? value.longTasks.count : 0,
+        totalMs: typeof value.longTasks?.totalMs === "number" ? value.longTasks.totalMs : 0,
+        maxMs: typeof value.longTasks?.maxMs === "number" ? value.longTasks.maxMs : 0,
+    };
+    const scriptingDurationMs = typeof value.scriptingDurationMs === "number" ? value.scriptingDurationMs : longTasks.totalMs;
+    const network = {
+        totalRequests: typeof value.network?.totalRequests === "number" ? value.network.totalRequests : 0,
+        totalBytes: typeof value.network?.totalBytes === "number" ? value.network.totalBytes : 0,
+        thirdPartyRequests: typeof value.network?.thirdPartyRequests === "number" ? value.network.thirdPartyRequests : 0,
+        thirdPartyBytes: typeof value.network?.thirdPartyBytes === "number" ? value.network.thirdPartyBytes : 0,
+        cacheHitRatio: typeof value.network?.cacheHitRatio === "number" ? value.network.cacheHitRatio : 0,
+        lateScriptRequests: typeof value.network?.lateScriptRequests === "number" ? value.network.lateScriptRequests : 0,
+    };
+    return { timings: { ttfbMs, domContentLoadedMs, loadMs }, vitals: { lcpMs, cls, inpMs }, longTasks, scriptingDurationMs, network };
+}
+async function createTargetSession(client) {
+    const created = await client.send("Target.createTarget", { url: "about:blank" });
+    const attached = await client.send("Target.attachToTarget", { targetId: created.targetId, flatten: true });
+    return { targetId: created.targetId, sessionId: attached.sessionId };
+}
+async function enableDomains(client, sessionId) {
+    await client.send("Page.enable", {}, sessionId);
+    await client.send("Log.enable", {}, sessionId);
+    await client.send("Runtime.enable", {}, sessionId);
+    await client.send("Performance.enable", {}, sessionId);
+}
+async function injectMeasurementScript(client, sessionId) {
+    const measurementScript = buildMeasureScript();
+    await client.send("Runtime.evaluate", { expression: measurementScript, awaitPromise: false }, sessionId);
+}
+async function navigateAndAwaitLoad(client, sessionId, url, timeoutMs) {
+    const response = await client.send("Page.navigate", { url }, sessionId);
+    if (response.errorText) {
+        throw new Error(response.errorText);
+    }
+    await client.waitForEventForSession("Page.loadEventFired", sessionId, timeoutMs);
+}
+async function evaluateMetrics(client, sessionId) {
+    const evaluateResult = await client.send("Runtime.evaluate", {
+        expression: `(() => {
+  const nav = performance.getEntriesByType('navigation')[0];
+  const state = (globalThis).__apexMeasure;
+  const resources = performance.getEntriesByType('resource');
+  const longTasks = performance.getEntriesByType('longtask');
+  let longTaskCount = 0;
+  let longTaskTotal = 0;
+  let longTaskMax = 0;
+  for (const lt of longTasks) {
+    const duration = lt.duration || 0;
+    longTaskCount += 1;
+    longTaskTotal += duration;
+    if (duration > longTaskMax) {
+      longTaskMax = duration;
+    }
+  }
+  let totalRequests = 0;
+  let totalBytes = 0;
+  let thirdPartyRequests = 0;
+  let thirdPartyBytes = 0;
+  let cacheHits = 0;
+  let lateScriptRequests = 0;
+  const pageHost = location.host;
+  const loadEnd = nav ? nav.loadEventEnd : 0;
+  for (const res of resources) {
+    totalRequests += 1;
+    const transfer = typeof res.transferSize === 'number' ? res.transferSize : 0;
+    const encoded = typeof res.encodedBodySize === 'number' ? res.encodedBodySize : 0;
+    totalBytes += transfer;
+    try {
+      const url = new URL(res.name, location.href);
+      const isThirdParty = url.host !== pageHost;
+      if (isThirdParty) {
+        thirdPartyRequests += 1;
+        thirdPartyBytes += transfer;
+      }
+    } catch {}
+    if ((transfer === 0 && encoded > 0) || (encoded > 0 && transfer < encoded)) {
+      cacheHits += 1;
+    }
+    if (res.initiatorType === 'script' && loadEnd && res.startTime >= loadEnd) {
+      lateScriptRequests += 1;
+    }
+  }
+  const cacheHitRatio = totalRequests > 0 ? cacheHits / totalRequests : 0;
+  return {
+    navigation: nav ? {
+      responseStart: nav.responseStart,
+      domContentLoadedEventEnd: nav.domContentLoadedEventEnd,
+      loadEventEnd: nav.loadEventEnd,
+    } : undefined,
+    vitals: state ? {
+      lcpMs: state.lcp,
+      cls: state.cls,
+      inpMs: state.inp,
+    } : undefined,
+    longTasks: {
+      count: longTaskCount,
+      totalMs: longTaskTotal,
+      maxMs: longTaskMax,
+    },
+    scriptingDurationMs: longTaskTotal,
+    network: {
+      totalRequests,
+      totalBytes,
+      thirdPartyRequests,
+      thirdPartyBytes,
+      cacheHitRatio,
+      lateScriptRequests,
+    },
+  };
+})()`,
+    }, sessionId);
+    const valueUnknown = evaluateResult.result?.value;
+    return parseMeasureResult(valueUnknown);
+}
+async function detachAndClose(client, context, stopLogging) {
+    stopLogging();
+    await client.send("Target.closeTarget", { targetId: context.targetId });
+    await client.send("Target.detachFromTarget", { sessionId: context.sessionId });
+}
+async function collectMetrics(params) {
+    const { client, task, sessionId, timeoutMs, artifactsDir, consoleErrors } = params;
+    const stopLogging = recordLogEvents(client, sessionId, consoleErrors);
+    await applyDeviceEmulation(client, task.device, sessionId);
+    await injectMeasurementScript(client, sessionId);
+    await navigateAndAwaitLoad(client, sessionId, task.url, timeoutMs);
+    const screenshotPath = await captureScreenshot(client, task, sessionId, artifactsDir);
+    await client.send("Runtime.evaluate", { expression: "void 0", awaitPromise: false }, sessionId);
+    const parsed = await evaluateMetrics(client, sessionId);
+    return { parsed, screenshotPath, stopLogging };
+}
+async function runSingleMeasure(params) {
+    const { client, task, timeoutMs, artifactsDir } = params;
+    let finalUrl = task.url;
+    const consoleErrors = [];
+    let screenshotPath;
+    try {
+        const context = await createTargetSession(client);
+        await enableDomains(client, context.sessionId);
+        const { parsed, screenshotPath: shotPath, stopLogging } = await collectMetrics({ client, task, sessionId: context.sessionId, timeoutMs, artifactsDir, consoleErrors });
+        screenshotPath = shotPath;
+        finalUrl = task.url;
+        await detachAndClose(client, context, stopLogging);
+        return {
+            url: finalUrl,
+            path: task.path,
+            label: task.label,
+            device: task.device,
+            timings: parsed.timings,
+            vitals: parsed.vitals,
+            longTasks: parsed.longTasks,
+            scriptingDurationMs: parsed.scriptingDurationMs,
+            network: parsed.network,
+            artifacts: { screenshotPath, consoleErrors },
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+            url: finalUrl,
+            path: task.path,
+            label: task.label,
+            device: task.device,
+            timings: {},
+            vitals: {},
+            longTasks: { count: 0, totalMs: 0, maxMs: 0 },
+            scriptingDurationMs: 0,
+            network: {
+                totalRequests: 0,
+                totalBytes: 0,
+                thirdPartyRequests: 0,
+                thirdPartyBytes: 0,
+                cacheHitRatio: 0,
+                lateScriptRequests: 0,
+            },
+            artifacts: { screenshotPath, consoleErrors },
+            runtimeErrorMessage: message,
+        };
+    }
+}
+async function runWithConcurrency(params) {
+    const results = new Array(params.tasks.length);
+    const nextIndex = { value: 0 };
+    const worker = async () => {
+        while (true) {
+            const index = nextIndex.value;
+            if (index >= params.tasks.length) {
+                return;
+            }
+            nextIndex.value += 1;
+            const task = params.tasks[index];
+            results[index] = await params.runner(task);
+        }
+    };
+    const workers = new Array(params.parallel).fill(0).map(async () => worker());
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Run fast, non-Lighthouse measurements across all page/device combos in the config.
+ */
+export async function runMeasureForConfig(params) {
+    const startedAtMs = Date.now();
+    const tasks = buildTasks(params.config);
+    const parallel = resolveParallelCount({ requested: params.parallelOverride ?? params.config.parallel, taskCount: tasks.length });
+    const timeoutMs = params.timeoutMs ?? DEFAULT_NAVIGATION_TIMEOUT_MS;
+    const artifactsDir = params.artifactsDir ?? DEFAULT_ARTIFACTS_DIR;
+    await mkdir(artifactsDir, { recursive: true });
+    const chrome = await createChromeSession();
+    try {
+        const version = await fetchJsonVersion(chrome.port);
+        const client = new CdpClient(version.webSocketDebuggerUrl);
+        await client.connect();
+        try {
+            const results = await runWithConcurrency({
+                tasks,
+                parallel,
+                runner: async (task) => runSingleMeasure({ client, task, timeoutMs, artifactsDir }),
+            });
+            const completedAtMs = Date.now();
+            const elapsedMs = completedAtMs - startedAtMs;
+            const averageComboMs = tasks.length > 0 ? Math.round(elapsedMs / tasks.length) : 0;
+            return {
+                meta: {
+                    configPath: params.configPath,
+                    resolvedParallel: parallel,
+                    comboCount: tasks.length,
+                    startedAt: new Date(startedAtMs).toISOString(),
+                    completedAt: new Date(completedAtMs).toISOString(),
+                    elapsedMs,
+                    averageComboMs,
+                },
+                results,
+            };
+        }
+        finally {
+            client.close();
+        }
+    }
+    finally {
+        await chrome.close();
+    }
+}

package/dist/measure-types.js

@@ -0,0 +1 @@
+export {};