audit0 0.1.0

package/dist/engine/artifacts.mjs

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { resolve, sep } from "node:path";
+const MEDIA_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+};
+export function portableArtifactPath(path) {
+    if (typeof path !== "string" || !path || path.startsWith("/") || path.includes("\\"))
+        return null;
+    const segments = path.split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === ".." || /[\u0000-\u001f\u007f]/.test(segment)))
+        return null;
+    const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+    return MEDIA_TYPES[extension] ? { path, mediaType: MEDIA_TYPES[extension] } : null;
+}
+export function referencedArtifacts(audit) {
+    const references = new Map();
+    const add = (path, reference) => {
+        const safe = portableArtifactPath(path);
+        if (!safe)
+            return;
+        if (!references.has(safe.path))
+            references.set(safe.path, { ...safe, references: [] });
+        references.get(safe.path).references.push(reference);
+    };
+    for (const [index, page] of audit.pages.entries()) {
+        add(page.screenshot, {
+            kind: "page-screenshot",
+            index,
+            id: page.id,
+            attempt: page.attempt,
+            mode: page.mode,
+        });
+    }
+    for (const [index, navigation] of audit.navigations.entries()) {
+        add(navigation.screenshot, {
+            kind: "navigation-screenshot",
+            index,
+            id: navigation.id,
+            attempt: navigation.attempt,
+            mode: navigation.mode,
+        });
+        for (const frame of navigation.measurement?.frames || []) {
+            add(`${navigation.directory}/${frame.file}`, {
+                kind: "navigation-frame",
+                index,
+                id: navigation.id,
+                attempt: navigation.attempt,
+                mode: navigation.mode,
+                atMs: frame.atMs,
+            });
+        }
+    }
+    return [...references.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+export async function buildArtifactManifest(directory, audit) {
+    const root = resolve(directory);
+    const physicalRoot = await realpath(root);
+    const files = [];
+    const missing = [];
+    for (const artifact of referencedArtifacts(audit)) {
+        const absolutePath = resolve(root, artifact.path);
+        if (!absolutePath.startsWith(`${root}${sep}`))
+            continue;
+        try {
+            const metadata = await lstat(absolutePath);
+            if (!metadata.isFile() || metadata.isSymbolicLink())
+                throw new Error("Artifact is not a regular file");
+            const physicalPath = await realpath(absolutePath);
+            if (!physicalPath.startsWith(`${physicalRoot}${sep}`))
+                throw new Error("Artifact leaves run directory");
+            const content = await readFile(physicalPath);
+            files.push({
+                ...artifact,
+                bytes: content.length,
+                sha256: createHash("sha256").update(content).digest("hex"),
+            });
+        }
+        catch {
+            missing.push(artifact);
+        }
+    }
+    return {
+        version: 1,
+        pathSemantics: "Paths are POSIX-style and relative to the directory containing audit.json.",
+        files,
+        missing,
+    };
+}

package/dist/engine/audit-archive.d.mts

@@ -0,0 +1,7 @@
+export declare function validateAuditDocument(audit: any): Promise<void>;
+export declare function validateArchiveEntryName(name: any): string;
+export declare function readAuditBundle(archivePath: any): Promise<{
+    audit: any;
+    entries: any;
+}>;
+export declare function writeAuditArchive(auditPath: any, outputPath?: string): Promise<string>;

package/dist/engine/audit-archive.mjs

@@ -0,0 +1,183 @@
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import Ajv from "ajv";
+import yauzl from "yauzl";
+import yazl from "yazl";
+import { portableArtifactPath } from "./artifacts.mjs";
+const MAX_ARCHIVE_BYTES = 300 * 1024 * 1024;
+const MAX_ENTRY_BYTES = 20 * 1024 * 1024;
+const MAX_AUDIT_JSON_BYTES = 128 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+const MAX_ENTRIES = 10002;
+const ZIP_EPOCH = new Date("1980-01-01T00:00:00.000Z");
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const schemaPath = fileURLToPath(new URL("../../schema/audit-v1.schema.json", import.meta.url));
+const schema = JSON.parse(await readFile(schemaPath, "utf8"));
+const ajv = new Ajv({ allErrors: true, strict: false });
+ajv.addFormat("date-time", { validate: (value) => ISO_DATE_TIME.test(value) });
+const validate = ajv.compile(schema);
+function assertOrigin(origin) {
+    const parsed = new URL(origin);
+    if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password) {
+        throw new Error("Audit environment.origin must be a credential-free HTTP(S) URL");
+    }
+}
+export async function validateAuditDocument(audit) {
+    if (!validate(audit)) {
+        throw new Error(`Audit schema validation failed: ${validate.errors.map((error) => `${error.instancePath || "/"} ${error.message}`).join("; ")}`);
+    }
+    assertOrigin(audit.environment.origin);
+    const paths = new Set();
+    for (const asset of audit.assets.files) {
+        const portable = portableArtifactPath(asset.path);
+        if (!portable || portable.path !== asset.path)
+            throw new Error(`Unsafe asset path: ${asset.path}`);
+        const folded = asset.path.normalize("NFC").toLowerCase();
+        if (paths.has(folded))
+            throw new Error(`Duplicate asset path: ${asset.path}`);
+        paths.add(folded);
+    }
+}
+function openZip(archivePath) {
+    return new Promise((resolveOpen, reject) => {
+        yauzl.open(archivePath, { lazyEntries: true, validateEntrySizes: true }, (error, zip) => {
+            if (error)
+                reject(error);
+            else
+                resolveOpen(zip);
+        });
+    });
+}
+function entryLimit(name) {
+    return name.normalize("NFC").toLowerCase() === "audit.json"
+        ? MAX_AUDIT_JSON_BYTES
+        : MAX_ENTRY_BYTES;
+}
+function readEntry(zip, entry) {
+    const limit = entryLimit(entry.fileName);
+    return new Promise((resolveRead, reject) => {
+        zip.openReadStream(entry, (error, stream) => {
+            if (error)
+                return reject(error);
+            const chunks = [];
+            let bytes = 0;
+            stream.on("data", (chunk) => {
+                bytes += chunk.length;
+                if (bytes > limit)
+                    stream.destroy(new Error(`Archive entry exceeds ${limit} bytes`));
+                else
+                    chunks.push(chunk);
+            });
+            stream.once("error", reject);
+            stream.once("end", () => resolveRead(Buffer.concat(chunks)));
+        });
+    });
+}
+export function validateArchiveEntryName(name) {
+    if (typeof name !== "string" ||
+        !name ||
+        name.includes("\\") ||
+        name.startsWith("/") ||
+        /^[a-z]:/i.test(name) ||
+        name.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new Error(`Unsafe archive entry: ${name}`);
+    }
+    return name;
+}
+async function readAuditArchive(archivePath) {
+    const archiveSize = (await stat(archivePath)).size;
+    if (archiveSize > MAX_ARCHIVE_BYTES)
+        throw new Error("Audit archive is too large");
+    const zip = await openZip(archivePath);
+    const entries = new Map();
+    let totalBytes = 0;
+    return new Promise((resolveEntries, reject) => {
+        const fail = (error) => {
+            zip.close();
+            reject(error);
+        };
+        zip.once("error", fail);
+        zip.on("entry", async (entry) => {
+            try {
+                if (entry.fileName.endsWith("/"))
+                    throw new Error(`Directories are not allowed in audit archives: ${entry.fileName}`);
+                validateArchiveEntryName(entry.fileName);
+                const mode = (entry.externalFileAttributes >>> 16) & 0o170000;
+                if (mode && mode !== 0o100000)
+                    throw new Error(`Non-regular archive entry: ${entry.fileName}`);
+                if (entry.uncompressedSize > entryLimit(entry.fileName) ||
+                    entry.uncompressedSize > Math.max(1024, entry.compressedSize * 100)) {
+                    throw new Error(`Unsafe archive entry size: ${entry.fileName}`);
+                }
+                const folded = entry.fileName.normalize("NFC").toLowerCase();
+                if (entries.has(folded))
+                    throw new Error(`Duplicate archive entry: ${entry.fileName}`);
+                if (entries.size >= MAX_ENTRIES)
+                    throw new Error("Audit archive has too many entries");
+                const content = await readEntry(zip, entry);
+                totalBytes += content.length;
+                if (totalBytes > MAX_TOTAL_BYTES)
+                    throw new Error("Audit archive expands beyond the allowed size");
+                entries.set(folded, { name: entry.fileName, content });
+                zip.readEntry();
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+        zip.once("end", () => resolveEntries(entries));
+        zip.readEntry();
+    });
+}
+export async function readAuditBundle(archivePath) {
+    const entries = await readAuditArchive(archivePath);
+    const auditEntry = entries.get("audit.json");
+    if (!auditEntry)
+        throw new Error("Audit archive must contain audit.json");
+    const audit = JSON.parse(auditEntry.content.toString("utf8"));
+    await validateAuditDocument(audit);
+    return { audit, entries };
+}
+export async function writeAuditArchive(auditPath, outputPath = resolve(dirname(auditPath), "audit.zip")) {
+    const sourceDirectory = dirname(auditPath);
+    const audit = JSON.parse(await readFile(auditPath, "utf8"));
+    audit.$schema = "./audit.schema.json";
+    delete audit.assets.publicBasePath;
+    await validateAuditDocument(audit);
+    const document = Buffer.from(JSON.stringify(audit, null, 2));
+    if (document.length > MAX_AUDIT_JSON_BYTES)
+        throw new Error(`audit.json exceeds ${MAX_AUDIT_JSON_BYTES} bytes`);
+    const schema = await readFile(schemaPath);
+    const zip = new yazl.ZipFile();
+    zip.addBuffer(document, "audit.json", {
+        mtime: ZIP_EPOCH,
+        mode: 0o100644,
+    });
+    zip.addBuffer(schema, "audit.schema.json", { mtime: ZIP_EPOCH, mode: 0o100644 });
+    for (const asset of audit.assets.files) {
+        const source = resolve(sourceDirectory, asset.path);
+        if (!source.startsWith(`${resolve(sourceDirectory)}${sep}`))
+            throw new Error(`Unsafe asset path: ${asset.path}`);
+        zip.addFile(source, `assets/${asset.path}`, {
+            mtime: ZIP_EPOCH,
+            mode: 0o100644,
+            compress: true,
+        });
+    }
+    const temporaryPath = `${outputPath}.${randomUUID()}.tmp`;
+    try {
+        zip.end();
+        await pipeline(zip.outputStream, createWriteStream(temporaryPath, { flags: "wx" }));
+        await readAuditBundle(temporaryPath);
+        await rename(temporaryPath, outputPath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true });
+        throw error;
+    }
+    return outputPath;
+}

package/dist/engine/findings.d.mts

@@ -0,0 +1,59 @@
+export declare const thresholds: {
+    ttfb: {
+        goodBelowMs: number;
+        okBelowMs: number;
+    };
+    feedback: {
+        goodBelowMs: number;
+        okBelowMs: number;
+    };
+    content: {
+        goodBelowMs: number;
+        badAboveMs: number;
+    };
+    images: {
+        earlyAfterTtfbMs: number;
+    };
+};
+export declare function gradeTiming(ms: any, metric: any): "bad" | "good" | "ok" | null;
+export declare function imageFinding(image: any): {
+    grade: string;
+    reason: string;
+} | {
+    grade: null;
+    reason: string;
+};
+export declare const navigationMetricTypes: {
+    clickToFeedbackMs: string;
+    clickToUrlMs: null;
+    clickToShellMs: string;
+    clickToUsefulMs: string;
+    clickToCompleteMs: string;
+};
+export declare function navigationFindings(record: any): {
+    [k: string]: {
+        grade: string | null;
+        ms: any;
+    };
+};
+export declare function pageFindings(record: any): {
+    ttfb: {
+        grade: string | null;
+        ms: any;
+    };
+    images: ({
+        grade: string;
+        reason: string;
+        url: any;
+        networkId: any;
+        isLcpCandidate: any;
+    } | {
+        grade: null;
+        reason: string;
+        url: any;
+        networkId: any;
+        isLcpCandidate: any;
+    })[];
+};
+export declare function recordIssue(record: any, phase: any, error: any): void;
+export declare function collectCase(record: any, work: any, cleanup?: () => Promise<void>): Promise<any>;

package/dist/engine/findings.mjs

@@ -0,0 +1,111 @@
+export const thresholds = {
+    ttfb: { goodBelowMs: 200, okBelowMs: 600 },
+    feedback: { goodBelowMs: 50, okBelowMs: 100 },
+    content: { goodBelowMs: 1000, badAboveMs: 3000 },
+    images: { earlyAfterTtfbMs: 100 },
+};
+export function gradeTiming(ms, metric) {
+    if (typeof ms !== "number" || !Number.isFinite(ms) || ms < 0)
+        return null;
+    const bands = thresholds[metric];
+    if (!bands)
+        return null;
+    if (metric === "content")
+        return ms < bands.goodBelowMs ? "good" : ms <= bands.badAboveMs ? "ok" : "bad";
+    return ms < bands.goodBelowMs ? "good" : ms < bands.okBelowMs ? "ok" : "bad";
+}
+export function imageFinding(image) {
+    const delay = image.fetchStartAfterTtfbMs;
+    const preload = (image.preloadEvidence || []).length > 0;
+    if (image.requestStatus === "failed" || (image.complete && image.naturalWidth === 0)) {
+        return { grade: "bad", reason: "Image request failed or image could not be decoded." };
+    }
+    if (typeof delay !== "number" || !Number.isFinite(delay)) {
+        return { grade: null, reason: "Fetch start relative to document first byte was not observed." };
+    }
+    if (delay > thresholds.images.earlyAfterTtfbMs) {
+        return {
+            grade: "bad",
+            reason: `Fetch began ${Math.round(delay)}ms after first byte; a preload or later priority upgrade does not erase late discovery.`,
+        };
+    }
+    if (image.requestStatus === "pending") {
+        return {
+            grade: "ok",
+            reason: "Fetch began early but was still pending at the observation cutoff.",
+        };
+    }
+    if (["High", "VeryHigh"].includes(image.initialPriority)) {
+        return {
+            grade: "good",
+            reason: preload
+                ? "Early fetch, high initial priority, and observed preload evidence."
+                : "Early fetch and high initial priority; preload was not confirmed.",
+        };
+    }
+    return {
+        grade: "ok",
+        reason: preload
+            ? "Preload observed and fetch began early, but high initial priority was not observed."
+            : "Fetch began early, but high initial priority/preload was not confirmed. Later upgrades are not initial priority.",
+    };
+}
+export const navigationMetricTypes = {
+    clickToFeedbackMs: "feedback",
+    clickToUrlMs: null,
+    clickToShellMs: "feedback",
+    clickToUsefulMs: "content",
+    clickToCompleteMs: "content",
+};
+export function navigationFindings(record) {
+    const measurement = record.measurement;
+    return Object.fromEntries(Object.entries(navigationMetricTypes).map(([metric, kind]) => [
+        metric,
+        {
+            grade: gradeTiming(measurement?.[metric], kind),
+            ms: measurement?.[metric] ?? null,
+        },
+    ]));
+}
+export function pageFindings(record) {
+    const diagnostics = record.diagnostics;
+    return {
+        ttfb: {
+            grade: gradeTiming(diagnostics?.navigation?.ttfbMs, "ttfb"),
+            ms: diagnostics?.navigation?.ttfbMs ?? null,
+        },
+        images: [
+            ...(diagnostics?.images?.final || []),
+            ...(diagnostics?.images?.backgrounds?.final || []),
+        ]
+            .filter((image) => image.visible && image.intersectsViewport)
+            .map((image) => ({
+            url: image.sourceUrl || image.url,
+            networkId: image.networkId,
+            isLcpCandidate: image.isLcpCandidate ?? null,
+            ...imageFinding(image),
+        })),
+    };
+}
+export function recordIssue(record, phase, error) {
+    const message = String(error?.message || error)
+        .split("\n")[0]
+        .replace(/https?:\/\/\S+/g, "[URL omitted]");
+    record.status = "failed";
+    record.error = [record.error, `${phase}: ${message}`].filter(Boolean).join("; ");
+}
+export async function collectCase(record, work, cleanup = async () => { }) {
+    try {
+        await work(record);
+    }
+    catch (error) {
+        recordIssue(record, "Collection", error);
+    }
+    try {
+        await cleanup(record);
+    }
+    catch (error) {
+        recordIssue(record, "Cleanup", error);
+    }
+    return record;
+}

package/dist/engine/inspect.d.mts

@@ -0,0 +1,36 @@
+/**
+ * Resolves an inspect target (a path or absolute URL) against the audit origin and refuses
+ * anything outside it.
+ */
+export declare function resolveInspectUrl(target: any, origin: any): string;
+export declare function formatInspectCapture(capture: any): string;
+/**
+ * Opens one URL like an audit case and saves evidence for writing markers and journeys:
+ * a screenshot, visible headings and same-origin links (with rendered size), ad-hoc selector
+ * counts, the configured page's marker state, and the main HTML. With `click`, it hovers and
+ * clicks the first visible `a[href]` whose attribute exactly equals `click` — the same target a
+ * journey uses — and captures again after the click, 1s and 5s.
+ *
+ * @param {object} options
+ * @param {string} options.url
+ * @param {string | null} [options.click]
+ * @param {string[]} [options.selectors]
+ * @param {readonly import("../config/types.ts").PageSpec[]} [options.pages]
+ * @param {import("../config/types.ts").AuditSettings} [options.settings]
+ * @param {string} [options.outputDirectory]
+ * @param {boolean} [options.headed]
+ * @param {(capture: any) => void} [options.onCapture] Called as each capture is saved.
+ */
+export declare function inspectUrl({ url, click, selectors, pages, settings, outputDirectory, headed, onCapture, }: {
+    url: string;
+    click?: string | null;
+    selectors?: string[];
+    pages?: readonly import("../config/types.ts").PageSpec[];
+    settings?: import("../config/types.ts").AuditSettings;
+    outputDirectory?: string;
+    headed?: boolean;
+    onCapture?: (capture: any) => void;
+}): Promise<{
+    directory: string;
+    captures: any[];
+}>;