apex-auditor 0.2.9 → 0.3.3

package/dist/lighthouse-worker.js

@@ -0,0 +1,248 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import lighthouse from "lighthouse";
+import { launch as launchChrome } from "chrome-launcher";
+function isTransientLighthouseError(error) {
+    const message = error instanceof Error && typeof error.message === "string" ? error.message : "";
+    return (message.includes("performance mark has not been set") ||
+        message.includes("TargetCloseError") ||
+        message.includes("Target closed") ||
+        message.includes("setAutoAttach") ||
+        message.includes("LanternError") ||
+        message.includes("top level events") ||
+        message.includes("CDP") ||
+        message.includes("disconnected") ||
+        message.includes("ApexAuditor timeout"));
+}
+async function createChromeSession() {
+    const userDataDir = await mkdtemp(join(tmpdir(), "apex-auditor-chrome-"));
+    const chrome = await launchChrome({
+        chromeFlags: [
+            "--headless=new",
+            "--disable-gpu",
+            "--no-sandbox",
+            "--disable-dev-shm-usage",
+            "--disable-extensions",
+            "--disable-default-apps",
+            "--no-first-run",
+            "--no-default-browser-check",
+            `--user-data-dir=${userDataDir}`,
+            "--disable-background-networking",
+            "--disable-background-timer-throttling",
+            "--disable-backgrounding-occluded-windows",
+            "--disable-renderer-backgrounding",
+            "--disable-client-side-phishing-detection",
+            "--disable-sync",
+            "--disable-translate",
+            "--metrics-recording-only",
+            "--safebrowsing-disable-auto-update",
+            "--password-store=basic",
+            "--use-mock-keychain",
+        ],
+    });
+    return {
+        port: chrome.port,
+        close: async () => {
+            try {
+                await chrome.kill();
+                await rm(userDataDir, { recursive: true, force: true });
+            }
+            catch {
+                return;
+            }
+        },
+    };
+}
+async function delayMs(durationMs) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, durationMs);
+    });
+}
+function computeRetryDelayMs(params) {
+    const baseDelayMs = 250;
+    const maxDelayMs = 5000;
+    const exp = Math.min(5, params.attempt);
+    const candidate = baseDelayMs * Math.pow(2, exp);
+    const jitter = Math.floor(Math.random() * 200);
+    return Math.min(maxDelayMs, candidate + jitter);
+}
+async function withTimeout(promise, timeoutMs) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => {
+            reject(new Error(`ApexAuditor timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]);
+}
+async function runTaskWithRetry(task, sessionRef, maxRetries) {
+    let attempt = 0;
+    let lastError;
+    while (attempt <= maxRetries) {
+        try {
+            return await withTimeout(runSingleAudit({
+                url: task.url,
+                path: task.path,
+                label: task.label,
+                device: task.device,
+                port: sessionRef.session.port,
+                logLevel: task.logLevel,
+                throttlingMethod: task.throttlingMethod,
+                cpuSlowdownMultiplier: task.cpuSlowdownMultiplier,
+                onlyCategories: task.onlyCategories,
+            }), task.timeoutMs);
+        }
+        catch (error) {
+            lastError = error;
+            const shouldRetry = isTransientLighthouseError(error) && attempt < maxRetries;
+            if (!shouldRetry) {
+                throw error instanceof Error ? error : new Error("Lighthouse failed");
+            }
+            await sessionRef.session.close();
+            await delayMs(computeRetryDelayMs({ attempt }));
+            sessionRef.session = await createChromeSession();
+            attempt += 1;
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error("Lighthouse failed after retries");
+}
+async function runSingleAudit(params) {
+    const onlyCategories = params.onlyCategories ?? ["performance", "accessibility", "best-practices", "seo"];
+    const throttling = params.throttlingMethod === "simulate"
+        ? {
+            cpuSlowdownMultiplier: params.cpuSlowdownMultiplier,
+            rttMs: 150,
+            throughputKbps: 1638.4,
+            requestLatencyMs: 150 * 3.75,
+            downloadThroughputKbps: 1638.4,
+            uploadThroughputKbps: 750,
+        }
+        : { cpuSlowdownMultiplier: params.cpuSlowdownMultiplier };
+    const options = {
+        port: params.port,
+        output: "json",
+        logLevel: params.logLevel,
+        onlyCategories,
+        formFactor: params.device,
+        throttlingMethod: params.throttlingMethod,
+        throttling,
+        screenEmulation: params.device === "mobile"
+            ? { mobile: true, width: 412, height: 823, deviceScaleFactor: 1.75, disabled: false }
+            : { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1, disabled: false },
+    };
+    const runnerResult = await lighthouse(params.url, options);
+    const lhrUnknown = runnerResult.lhr;
+    if (!lhrUnknown || typeof lhrUnknown !== "object") {
+        throw new Error("Lighthouse did not return a valid result");
+    }
+    const lhr = lhrUnknown;
+    const scores = extractScores(lhr);
+    const metrics = extractMetrics(lhr);
+    const opportunities = extractTopOpportunities(lhr, 3);
+    return {
+        url: lhr.finalDisplayedUrl ?? params.url,
+        path: params.path,
+        label: params.label,
+        device: params.device,
+        scores,
+        metrics,
+        opportunities,
+        runtimeErrorCode: typeof lhr.runtimeError?.code === "string" ? lhr.runtimeError.code : undefined,
+        runtimeErrorMessage: typeof lhr.runtimeError?.message === "string" ? lhr.runtimeError.message : undefined,
+    };
+}
+function extractScores(lhr) {
+    const performanceScore = lhr.categories.performance?.score;
+    const accessibilityScore = lhr.categories.accessibility?.score;
+    const bestPracticesScore = lhr.categories["best-practices"]?.score;
+    const seoScore = lhr.categories.seo?.score;
+    return {
+        performance: normaliseScore(performanceScore),
+        accessibility: normaliseScore(accessibilityScore),
+        bestPractices: normaliseScore(bestPracticesScore),
+        seo: normaliseScore(seoScore),
+    };
+}
+function normaliseScore(score) {
+    if (typeof score !== "number") {
+        return undefined;
+    }
+    return Math.round(score * 100);
+}
+function extractMetrics(lhr) {
+    const audits = lhr.audits;
+    const lcpAudit = audits["largest-contentful-paint"];
+    const fcpAudit = audits["first-contentful-paint"];
+    const tbtAudit = audits["total-blocking-time"];
+    const clsAudit = audits["cumulative-layout-shift"];
+    const inpAudit = audits["interaction-to-next-paint"];
+    const lcpMs = typeof lcpAudit?.numericValue === "number" ? lcpAudit.numericValue : undefined;
+    const fcpMs = typeof fcpAudit?.numericValue === "number" ? fcpAudit.numericValue : undefined;
+    const tbtMs = typeof tbtAudit?.numericValue === "number" ? tbtAudit.numericValue : undefined;
+    const cls = typeof clsAudit?.numericValue === "number" ? clsAudit.numericValue : undefined;
+    const inpMs = typeof inpAudit?.numericValue === "number" ? inpAudit.numericValue : undefined;
+    return {
+        lcpMs,
+        fcpMs,
+        tbtMs,
+        cls,
+        inpMs,
+    };
+}
+function extractTopOpportunities(lhr, limit) {
+    const audits = Object.values(lhr.audits);
+    const candidates = audits
+        .filter((audit) => audit.details?.type === "opportunity")
+        .map((audit) => {
+        const savingsMs = audit.details?.overallSavingsMs;
+        const savingsBytes = audit.details?.overallSavingsBytes;
+        return {
+            id: audit.id ?? "unknown",
+            title: audit.title ?? (audit.id ?? "Unknown"),
+            estimatedSavingsMs: typeof savingsMs === "number" ? savingsMs : undefined,
+            estimatedSavingsBytes: typeof savingsBytes === "number" ? savingsBytes : undefined,
+        };
+    });
+    candidates.sort((a, b) => (b.estimatedSavingsMs ?? 0) - (a.estimatedSavingsMs ?? 0));
+    return candidates.slice(0, limit);
+}
+function send(message) {
+    if (typeof process.send === "function") {
+        process.send(message);
+    }
+}
+async function main() {
+    const maxRetries = 2;
+    const maxTasksPerChrome = 20;
+    const sessionRef = { session: await createChromeSession() };
+    let tasksSinceChromeStart = 0;
+    process.on("message", async (raw) => {
+        const message = raw && typeof raw === "object" ? raw : undefined;
+        if (!message || message.type !== "run") {
+            return;
+        }
+        try {
+            const result = await runTaskWithRetry(message.task, sessionRef, maxRetries);
+            send({ type: "result", id: message.id, result });
+            tasksSinceChromeStart += 1;
+            if (tasksSinceChromeStart >= maxTasksPerChrome) {
+                tasksSinceChromeStart = 0;
+                await sessionRef.session.close();
+                sessionRef.session = await createChromeSession();
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : "Unknown error";
+            send({ type: "error", id: message.id, errorMessage });
+            try {
+                await sessionRef.session.close();
+            }
+            catch {
+                return;
+            }
+            sessionRef.session = await createChromeSession();
+            tasksSinceChromeStart = 0;
+        }
+    });
+}
+void main();

package/dist/measure-cli.js

@@ -0,0 +1,139 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { loadConfig } from "./config.js";
+import { runMeasureForConfig } from "./measure-runner.js";
+function printSummary(summary) {
+    const combos = summary.meta.comboCount;
+    if (combos === 0) {
+        // eslint-disable-next-line no-console
+        console.log("No measure results.");
+        return;
+    }
+    let longTaskCount = 0;
+    let longTaskTotalMs = 0;
+    let longTaskMaxMs = 0;
+    let scriptingTotalMs = 0;
+    let scriptingCount = 0;
+    let totalRequests = 0;
+    let totalBytes = 0;
+    let thirdPartyRequests = 0;
+    let thirdPartyBytes = 0;
+    let cacheHitsApprox = 0;
+    let lateScripts = 0;
+    for (const r of summary.results) {
+        longTaskCount += r.longTasks.count;
+        longTaskTotalMs += r.longTasks.totalMs;
+        longTaskMaxMs = Math.max(longTaskMaxMs, r.longTasks.maxMs);
+        if (r.scriptingDurationMs !== undefined) {
+            scriptingTotalMs += r.scriptingDurationMs;
+            scriptingCount += 1;
+        }
+        totalRequests += r.network.totalRequests;
+        totalBytes += r.network.totalBytes;
+        thirdPartyRequests += r.network.thirdPartyRequests;
+        thirdPartyBytes += r.network.thirdPartyBytes;
+        cacheHitsApprox += Math.round(r.network.cacheHitRatio * r.network.totalRequests);
+        lateScripts += r.network.lateScriptRequests;
+    }
+    const avgScriptingMs = scriptingCount > 0 ? Math.round(scriptingTotalMs / scriptingCount) : 0;
+    const cacheHitRatio = totalRequests > 0 ? cacheHitsApprox / totalRequests : 0;
+    const thirdPartyShare = totalRequests > 0 ? thirdPartyRequests / totalRequests : 0;
+    // eslint-disable-next-line no-console
+    console.log([
+        "Summary:",
+        `  Combos: ${combos}`,
+        `  Long tasks: ${longTaskCount} tasks, total ${Math.round(longTaskTotalMs)}ms, max ${Math.round(longTaskMaxMs)}ms`,
+        `  Scripting: avg ${avgScriptingMs}ms`,
+        `  Network: ${totalRequests} requests, ${Math.round(totalBytes / 1024)} KB; 3P ${thirdPartyRequests} (${Math.round(thirdPartyShare * 100)}%), cache-hit ${Math.round(cacheHitRatio * 100)}%, late scripts ${lateScripts}`,
+    ].join("\n"));
+}
+function parseArgs(argv) {
+    let configPath;
+    let deviceFilter;
+    let parallelOverride;
+    let timeoutMs;
+    let jsonOutput = false;
+    for (let i = 2; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if ((arg === "--config" || arg === "-c") && i + 1 < argv.length) {
+            configPath = argv[i + 1];
+            i += 1;
+        }
+        else if (arg === "--mobile-only") {
+            deviceFilter = "mobile";
+        }
+        else if (arg === "--desktop-only") {
+            deviceFilter = "desktop";
+        }
+        else if (arg === "--parallel" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value < 1 || value > 10) {
+                throw new Error(`Invalid --parallel value: ${argv[i + 1]}. Expected integer between 1 and 10.`);
+            }
+            parallelOverride = value;
+            i += 1;
+        }
+        else if (arg === "--timeout-ms" && i + 1 < argv.length) {
+            const value = parseInt(argv[i + 1], 10);
+            if (Number.isNaN(value) || value <= 0) {
+                throw new Error(`Invalid --timeout-ms value: ${argv[i + 1]}. Expected a positive integer.`);
+            }
+            timeoutMs = value;
+            i += 1;
+        }
+        else if (arg === "--json") {
+            jsonOutput = true;
+        }
+    }
+    return { configPath: configPath ?? "apex.config.json", deviceFilter, parallelOverride, timeoutMs, jsonOutput };
+}
+function filterConfigDevices(config, deviceFilter) {
+    if (!deviceFilter) {
+        return config;
+    }
+    const pages = config.pages
+        .map((page) => {
+        const devices = page.devices.filter((d) => d === deviceFilter);
+        return { path: page.path, label: page.label, devices };
+    })
+        .filter((p) => p.devices.length > 0);
+    return { ...config, pages };
+}
+/**
+ * Runs the ApexAuditor measure CLI (fast batch metrics, non-Lighthouse).
+ *
+ * @param argv - The process arguments array.
+ */
+export async function runMeasureCli(argv) {
+    const args = parseArgs(argv);
+    const { configPath, config } = await loadConfig({ configPath: args.configPath });
+    const filteredConfig = filterConfigDevices(config, args.deviceFilter);
+    if (filteredConfig.pages.length === 0) {
+        // eslint-disable-next-line no-console
+        console.error("No pages remain after applying device filter.");
+        process.exitCode = 1;
+        return;
+    }
+    const outputDir = resolve(".apex-auditor");
+    const artifactsDir = resolve(outputDir, "measure");
+    await mkdir(outputDir, { recursive: true });
+    await mkdir(artifactsDir, { recursive: true });
+    const summary = await runMeasureForConfig({
+        config: filteredConfig,
+        configPath,
+        parallelOverride: args.parallelOverride,
+        timeoutMs: args.timeoutMs,
+        artifactsDir,
+    });
+    await writeFile(resolve(outputDir, "measure-summary.json"), JSON.stringify(summary, null, 2), "utf8");
+    if (args.jsonOutput) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`Measured ${summary.meta.comboCount} combos in ${Math.round(summary.meta.elapsedMs / 1000)}s (avg ${summary.meta.averageComboMs}ms/combo).`);
+    // eslint-disable-next-line no-console
+    console.log(`Wrote .apex-auditor/measure-summary.json`);
+    printSummary(summary);
+}