audit0 0.1.0

package/dist/infra.js

@@ -0,0 +1,2 @@
+export { buildArtifactManifest } from "./engine/artifacts.mjs";
+export { validateAuditDocument, readAuditBundle } from "./engine/audit-archive.mjs";

package/dist/run.d.ts

@@ -0,0 +1,30 @@
+import type { AuditConfig } from "./config/types.ts";
+type CaseRecord = Record<string, any>;
+export interface AuditDocument {
+    schemaVersion: number;
+    startedAt: string;
+    finishedAt: string | null;
+    provenance: Record<string, unknown>;
+    environment: Record<string, unknown>;
+    settings: Record<string, unknown>;
+    observations: string[];
+    pages: CaseRecord[];
+    navigations: CaseRecord[];
+    assets?: unknown;
+}
+export interface RunOptions {
+    repeats?: number;
+    only?: string[];
+    pagesOnly?: boolean;
+    navigationOnly?: boolean;
+    headed?: boolean;
+    outputDirectory?: string;
+}
+export interface AuditResult {
+    directory: string;
+    reportPath: string;
+    archivePath: string;
+    audit: AuditDocument;
+}
+export declare function runAudit(config: AuditConfig, options?: RunOptions): Promise<AuditResult>;
+export {};

package/dist/run.js

@@ -0,0 +1,319 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { arch, platform } from "node:os";
+import { resolve } from "node:path";
+import { AuditConfigError } from "./config/errors.js";
+import { buildArtifactManifest } from "./engine/artifacts.mjs";
+import { writeAuditArchive } from "./engine/audit-archive.mjs";
+import { collectCase, navigationFindings, pageFindings, recordIssue, thresholds, } from "./engine/findings.mjs";
+import { startNavigationRequestCapture } from "./engine/navigation-requests.mjs";
+import { inspectState, measureNavigation, waitForContent } from "./engine/navigation.mjs";
+import { startPageDiagnostics } from "./engine/page-diagnostics.mjs";
+import { writeReport } from "./engine/report.mjs";
+function resolveOrigin(config) {
+    const origin = process.env.AUDIT_ORIGIN ?? config.origin;
+    const parsed = new URL(origin);
+    if (!["http:", "https:"].includes(parsed.protocol) ||
+        parsed.username ||
+        parsed.password ||
+        parsed.search ||
+        parsed.hash ||
+        parsed.pathname !== "/") {
+        throw new AuditConfigError("invalid-config", "origin", "AUDIT_ORIGIN must be a credential-free HTTP(S) origin without a path, query or fragment");
+    }
+    return origin;
+}
+export async function runAudit(config, options = {}) {
+    const repeats = options.repeats ?? config.settings.repeats;
+    if (!Number.isInteger(repeats) || repeats < 1 || repeats > 20) {
+        throw new AuditConfigError("invalid-config", "repeats", "repeats must be an integer from 1 to 20");
+    }
+    const only = options.only ?? [];
+    const skipPages = options.navigationOnly ?? false;
+    const skipNavigations = options.pagesOnly ?? false;
+    const headless = !(options.headed ?? false);
+    const settings = config.settings;
+    const origin = resolveOrigin(config);
+    const outputDirectory = resolve(options.outputDirectory ?? "artifacts");
+    const directory = resolve(outputDirectory, `run-${new Date().toISOString().replaceAll(":", "-")}`);
+    await mkdir(directory, { recursive: true });
+    let launchError;
+    const { chromium } = await import("@playwright/test");
+    const browser = await chromium.launch({ headless }).catch((error) => {
+        launchError = error;
+        return null;
+    });
+    const audit = {
+        schemaVersion: 1,
+        startedAt: new Date().toISOString(),
+        finishedAt: null,
+        provenance: {
+            commit: process.env.GITHUB_SHA ?? null,
+            ref: process.env.GITHUB_REF_NAME ?? null,
+            repository: process.env.GITHUB_REPOSITORY ?? null,
+            runUrl: process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
+                ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+                : null,
+        },
+        environment: {
+            origin,
+            browserVersion: browser?.version() ?? "unavailable",
+            headless,
+            viewport: settings.viewport,
+            platform: `${platform()} ${arch()}`,
+            network: "unthrottled",
+            cpu: "unthrottled",
+            anonymous: true,
+            browserCache: "enabled; fresh context per attempt",
+            cdnCache: "uncontrolled; response headers recorded",
+            colorScheme: "light",
+            timezone: "UTC",
+            locale: "en-US",
+        },
+        settings: { ...settings, repeats, thresholds },
+        observations: [],
+        pages: [],
+        navigations: [],
+    };
+    const contextOptions = {
+        viewport: settings.viewport,
+        colorScheme: "light",
+        timezoneId: "UTC",
+        locale: "en-US",
+    };
+    async function newContext() {
+        if (!browser)
+            throw launchError;
+        return browser.newContext(contextOptions);
+    }
+    async function save() {
+        audit.finishedAt = new Date().toISOString();
+        audit.observations = [
+            "Cases are reporting-only: poor metrics, missing content and individual collection errors do not stop remaining cases or fail the command.",
+            "Desktop anonymous synthetic baseline only. Font and image diagnoses require the per-page source/priority evidence; local fallback fonts are not network blockers.",
+        ];
+        audit.assets = await buildArtifactManifest(directory, audit);
+        await writeFile(`${directory}/audit.json`, JSON.stringify(audit, null, 2));
+    }
+    async function measurePage(spec, holder, attempt, mode) {
+        let diagnostics;
+        const record = {
+            id: spec.id,
+            path: spec.path,
+            attempt,
+            mode,
+            status: "ok",
+            screenshot: `pages/${spec.id}-${attempt}-${mode}.png`,
+        };
+        await collectCase(record, async () => {
+            if (!holder.context)
+                holder.context = await newContext();
+            if (!holder.page || holder.page.isClosed())
+                holder.page = await holder.context.newPage();
+            const page = holder.page;
+            await collectCase(record, async () => {
+                diagnostics = await startPageDiagnostics(page);
+            });
+            if (mode === "warm-reload" && new URL(page.url()).pathname !== spec.path) {
+                recordIssue(record, "Warm reload", "Original document was not available; this is a recovery navigation, not a warm sample");
+                record.mode = "recovery-navigation";
+            }
+            const response = record.mode === "warm-reload"
+                ? await page.reload({ waitUntil: "domcontentloaded", timeout: 60000 })
+                : await page.goto(new URL(spec.path, origin).href, {
+                    waitUntil: "domcontentloaded",
+                    timeout: 60000,
+                });
+            const finalPath = new URL(page.url()).pathname;
+            if (!response?.ok())
+                recordIssue(record, "Document", `HTTP ${response?.status() ?? "missing"}`);
+            else if (finalPath !== spec.path)
+                recordIssue(record, "Path", `Redirected to ${finalPath}; pages are matched on location.pathname, so set this page's path to ${finalPath}`);
+            else
+                await collectCase(record, () => waitForContent(page, spec));
+            await page.waitForTimeout(settings.pageObservationMs);
+        }, async () => {
+            if (diagnostics) {
+                const pending = diagnostics;
+                await collectCase(record, async () => {
+                    record.diagnostics = await pending.finish();
+                });
+            }
+            if (holder.page) {
+                await collectCase(record, async () => {
+                    record.finalState = await holder.page.evaluate(inspectState, spec);
+                });
+                await collectCase(record, () => holder
+                    .page.screenshot({ path: `${directory}/${record.screenshot}`, timeout: 10000 })
+                    .catch((error) => {
+                    record.screenshot = null;
+                    throw error;
+                }));
+            }
+            else
+                record.screenshot = null;
+            if (!record.finalState?.primary) {
+                recordIssue(record, "Content", "Useful page content missing at final collection");
+            }
+        });
+        const ttfb = pageFindings(record).ttfb;
+        audit.pages.push(record);
+        console.log(`page ${spec.path} ${record.mode}; TTFB ${ttfb.grade ?? "unmeasured"} ${ttfb.ms?.toFixed(0) ?? "?"}ms; collection ${record.status === "ok" ? "complete" : "incomplete"}`);
+        await save();
+    }
+    async function measureJourney(journey, attempt, mode, holder) {
+        const source = config.pages.find((page) => page.id === journey.from);
+        const target = config.pages.find((page) => page.id === journey.to);
+        if (!source || !target) {
+            throw new AuditConfigError("unknown-page", `journeys.${journey.id}`, `journey references pages that are not defined`);
+        }
+        let requestCapture;
+        const folder = `navigations/${journey.id}-${attempt}-${mode}`;
+        const record = {
+            id: journey.id,
+            from: source.path,
+            to: target.path,
+            attempt,
+            mode,
+            status: "ok",
+            criteria: target,
+            directory: folder,
+            screenshot: `${folder}/final.png`,
+        };
+        await collectCase(record, async () => {
+            await mkdir(`${directory}/${folder}`, { recursive: true });
+            if (!holder.context)
+                holder.context = await newContext();
+            if (!holder.page || holder.page.isClosed())
+                holder.page = await holder.context.newPage();
+            const page = holder.page;
+            requestCapture = await startNavigationRequestCapture(page, new URL(target.path, origin).href);
+            if (mode === "revisit") {
+                if (new URL(page.url()).pathname !== target.path) {
+                    throw new Error("Revisit requires the completed first visit destination in the same page");
+                }
+                await page.goBack({ waitUntil: "domcontentloaded", timeout: 60000 });
+            }
+            else {
+                await page.goto(new URL(source.path, origin).href, {
+                    waitUntil: "domcontentloaded",
+                    timeout: 60000,
+                });
+            }
+            await waitForContent(page, source);
+            await page.waitForTimeout(settings.sourceDwellMs);
+            record.measurement = await measureNavigation(page, target, {
+                directory: `${directory}/${folder}`,
+                observeMs: settings.navigationObservationMs,
+                requireClientReady: mode === "client-ready-first-visit",
+                requestCapture,
+                settings,
+            });
+            if (record.measurement.clickToUsefulMs === null) {
+                throw new Error("Useful destination content not observed within the measurement window");
+            }
+            if (!record.measurement.finalState?.primary) {
+                throw new Error("Useful content did not survive until final collection");
+            }
+            if (record.measurement.collectionErrors.length) {
+                throw new Error("Instrumentation incomplete; inspect measurement.collectionErrors");
+            }
+        }, async () => {
+            if (holder.page) {
+                await collectCase(record, () => holder
+                    .page.screenshot({ path: `${directory}/${record.screenshot}`, timeout: 10000 })
+                    .catch((error) => {
+                    record.screenshot = null;
+                    throw error;
+                }));
+            }
+            else
+                record.screenshot = null;
+            if (!record.measurement && requestCapture) {
+                const pending = requestCapture;
+                await collectCase(record, () => pending.dispose());
+            }
+        });
+        const findings = navigationFindings(record);
+        audit.navigations.push(record);
+        console.log(`navigation ${journey.id} ${mode}; feedback ${findings.clickToFeedbackMs?.grade ?? "unmeasured"} ${record.measurement?.clickToFeedbackMs?.toFixed(0) ?? "?"}ms; useful ${findings.clickToUsefulMs?.grade ?? "unmeasured"} ${record.measurement?.clickToUsefulMs?.toFixed(0) ?? "?"}ms; collection ${record.status === "ok" ? "complete" : "incomplete"}`);
+        await save();
+        return record;
+    }
+    let result;
+    try {
+        await mkdir(`${directory}/pages`, { recursive: true });
+        if (!skipPages) {
+            for (const spec of config.pages.filter((page) => only.length === 0 || only.includes(page.id))) {
+                for (let attempt = 1; attempt <= repeats; attempt++) {
+                    const holder = {};
+                    try {
+                        await measurePage(spec, holder, attempt, "fresh-context");
+                        await measurePage(spec, holder, attempt, "warm-reload");
+                    }
+                    finally {
+                        if (holder.context) {
+                            const last = audit.pages.at(-1);
+                            if (last)
+                                await collectCase(last, () => holder.context.close());
+                        }
+                    }
+                }
+            }
+        }
+        if (!skipNavigations) {
+            const journeys = config.journeys.filter((journey) => only.length === 0 || only.includes(journey.id) || only.includes(journey.to));
+            for (const journey of journeys) {
+                for (let attempt = 1; attempt <= repeats; attempt++) {
+                    const sequence = {};
+                    let firstVisit;
+                    try {
+                        firstVisit = await measureJourney(journey, attempt, "first-visit", sequence);
+                        await measureJourney(journey, attempt, "revisit", sequence);
+                    }
+                    finally {
+                        if (sequence.context) {
+                            const last = audit.navigations.at(-1);
+                            if (last)
+                                await collectCase(last, () => sequence.context.close());
+                        }
+                    }
+                    if (firstVisit?.measurement?.type === "full-document") {
+                        const retry = {};
+                        try {
+                            await measureJourney(journey, attempt, "client-ready-first-visit", retry);
+                        }
+                        finally {
+                            if (retry.context) {
+                                const last = audit.navigations.at(-1);
+                                if (last)
+                                    await collectCase(last, () => retry.context.close());
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        if (!audit.pages.length && !audit.navigations.length) {
+            throw new AuditConfigError("invalid-config", "only", "No matching cases selected");
+        }
+    }
+    finally {
+        try {
+            await save();
+            const reportPath = await writeReport(audit, directory);
+            const archivePath = await writeAuditArchive(`${directory}/audit.json`);
+            await writeFile(`${outputDirectory}/latest.json`, JSON.stringify({ directory }, null, 2));
+            console.log(`Report: ${reportPath}`);
+            console.log(`Bundle: ${archivePath}`);
+            result = { directory, reportPath, archivePath, audit };
+        }
+        finally {
+            await browser
+                ?.close()
+                .catch((error) => console.warn(`Browser cleanup: ${error.message.split("\n")[0]}`));
+        }
+    }
+    if (!result)
+        throw new Error("Audit did not produce a result");
+    return result;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "audit0",
+  "version": "0.1.0",
+  "description": "Engine and authoring SDK for browser performance and UX audits",
+  "license": "MIT",
+  "bin": {
+    "audit0": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    },
+    "./infra": {
+      "types": "./dist/infra.d.ts",
+      "default": "./dist/infra.js"
+    },
+    "./findings": {
+      "types": "./dist/findings.d.ts",
+      "default": "./dist/findings.js"
+    },
+    "./schema.json": "./schema/audit-v1.schema.json",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "ajv": "8.17.1",
+    "yauzl": "3.2.0",
+    "yazl": "3.3.1",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.63.0",
+    "@types/node": "24.0.1",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.63.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.mjs test/*.test.ts"
+  }
+}

package/schema/audit-v1.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:audit0:audit:v1",
+  "title": "Browser audit report",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "startedAt",
+    "finishedAt",
+    "environment",
+    "settings",
+    "observations",
+    "pages",
+    "navigations",
+    "assets"
+  ],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1, "maxLength": 160 },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": "string", "format": "date-time" },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "environment": {
+      "type": "object",
+      "required": ["origin"],
+      "additionalProperties": true
+    },
+    "settings": { "type": "object", "additionalProperties": true },
+    "observations": { "type": "array" },
+    "pages": {
+      "type": "array",
+      "maxItems": 10000,
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "navigations": {
+      "type": "array",
+      "maxItems": 10000,
+      "items": { "type": "object", "additionalProperties": true }
+    },
+    "assets": {
+      "type": "object",
+      "required": ["version", "files", "missing"],
+      "properties": {
+        "version": { "const": 1 },
+        "pathSemantics": { "type": "string" },
+        "publicBasePath": { "type": "string" },
+        "files": {
+          "type": "array",
+          "maxItems": 10000,
+          "items": { "$ref": "#/definitions/asset" }
+        },
+        "missing": {
+          "type": "array",
+          "maxItems": 10000,
+          "items": { "type": "object", "additionalProperties": true }
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "asset": {
+      "type": "object",
+      "required": ["path", "mediaType", "bytes", "sha256", "references"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1, "maxLength": 1024 },
+        "mediaType": {
+          "enum": ["image/jpeg", "image/png", "image/webp"]
+        },
+        "bytes": { "type": "integer", "minimum": 0, "maximum": 20971520 },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "references": { "type": "array" }
+      },
+      "additionalProperties": true
+    }
+  }
+}