audit0 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function cli(argv: string[]): Promise<void>;
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { realpathSync } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { AuditConfigError } from "./config/errors.js";
+import { buildArtifactManifest } from "./engine/artifacts.mjs";
+import { validateAuditDocument, readAuditBundle, writeAuditArchive, } from "./engine/audit-archive.mjs";
+import { writeReport } from "./engine/report.mjs";
+const CONFIG_CANDIDATES = ["audit.config.ts", "audit.config.mjs", "audit.config.js"];
+const USAGE = `Usage: audit0 <command> [options]
+
+Commands:
+  run [options]                  Run the configured pages and journeys
+    --repeats <n>                Repetitions per case (1-20)
+    --only <id>                  Restrict to a page or journey id (repeatable)
+    --pages-only                 Skip journeys
+    --navigation-only            Skip pages
+    --headed                     Run a headed browser
+    --output <dir>               Artifact directory (default: artifacts)
+    --config <path>              Config file (default: audit.config.ts|mjs|js)
+  inspect <path|url> [options]   Capture a page's links, headings, markers and HTML
+    --click <href>               Hover and click the visible link with this exact href
+    --selector <css>             Count matches and audit-visible matches (repeatable)
+    --origin <url>               Origin for relative paths (default: AUDIT_ORIGIN or config)
+    --output <dir>               Evidence directory (default: artifacts/inspect)
+    --config <path>              Config whose page markers are evaluated (optional)
+    --headed                     Run a headed browser
+  report <audit.json>            Render report.html beside the audit
+  archive [run|audit.json] [out] Write audit.zip
+  archive verify <audit.zip>     Verify a bundle
+  assets [run|audit.json]        Rebuild the asset manifest
+  validate <audit.json>          Validate an audit document
+`;
+function write(chunk) {
+    process.stdout.write(chunk);
+}
+function writeError(chunk) {
+    process.stderr.write(chunk);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function findDefaultConfig() {
+    for (const candidate of CONFIG_CANDIDATES) {
+        const path = resolve(candidate);
+        if (await exists(path))
+            return path;
+    }
+    return null;
+}
+async function findConfig(explicit) {
+    if (explicit)
+        return resolve(explicit);
+    const found = await findDefaultConfig();
+    if (found)
+        return found;
+    throw new AuditConfigError("invalid-config", "", `no config found; looked for ${CONFIG_CANDIDATES.join(", ")}`);
+}
+async function loadConfig(explicit) {
+    const file = await findConfig(explicit);
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    if (module.default)
+        return module.default;
+    throw new AuditConfigError("invalid-config", "", `config ${file} must default-export defineAudit(...)`);
+}
+function parseRunOptions(args) {
+    const options = { only: [] };
+    let configPath;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--repeats")
+            options.repeats = Number(args[++index]);
+        else if (arg === "--only")
+            options.only?.push(args[++index] ?? "");
+        else if (arg === "--pages-only")
+            options.pagesOnly = true;
+        else if (arg === "--navigation-only")
+            options.navigationOnly = true;
+        else if (arg === "--headed")
+            options.headed = true;
+        else if (arg === "--output")
+            options.outputDirectory = args[++index];
+        else if (arg === "--config")
+            configPath = args[++index];
+        else
+            throw new AuditConfigError("invalid-config", "", `unknown option "${arg}"`);
+    }
+    return { options, configPath };
+}
+function parseInspectArgs(args) {
+    const parsed = { selectors: [], headed: false };
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--click")
+            parsed.click = args[++index];
+        else if (arg === "--selector")
+            parsed.selectors.push(args[++index] ?? "");
+        else if (arg === "--origin")
+            parsed.origin = args[++index];
+        else if (arg === "--output")
+            parsed.outputDirectory = args[++index];
+        else if (arg === "--config")
+            parsed.configPath = args[++index];
+        else if (arg === "--headed")
+            parsed.headed = true;
+        else if (arg.startsWith("--") || parsed.target !== undefined)
+            throw new AuditConfigError("invalid-config", "", `unknown inspect argument "${arg}"`);
+        else
+            parsed.target = arg;
+    }
+    return parsed;
+}
+async function commandInspect(args) {
+    const parsed = parseInspectArgs(args);
+    if (!parsed.target) {
+        throw new AuditConfigError("invalid-config", "", "Usage: audit0 inspect <path|url> [--click <href>] [--selector <css>]");
+    }
+    const configPath = parsed.configPath ? resolve(parsed.configPath) : await findDefaultConfig();
+    const config = configPath ? await loadConfig(configPath) : null;
+    const { formatInspectCapture, inspectUrl, resolveInspectUrl } = await import("./engine/inspect.mjs");
+    const { directory } = await inspectUrl({
+        url: resolveInspectUrl(parsed.target, parsed.origin ?? process.env.AUDIT_ORIGIN ?? config?.origin),
+        click: parsed.click ?? null,
+        selectors: parsed.selectors,
+        pages: config?.pages ?? [],
+        settings: config?.settings,
+        outputDirectory: parsed.outputDirectory,
+        headed: parsed.headed,
+        onCapture: (capture) => write(formatInspectCapture(capture)),
+    });
+    write(`Evidence: ${directory}\n`);
+}
+async function resolveAuditPath(supplied) {
+    if (supplied) {
+        const resolved = resolve(supplied);
+        return resolved.endsWith(".json") ? resolved : resolve(resolved, "audit.json");
+    }
+    const latest = JSON.parse(await readFile(resolve("artifacts/latest.json"), "utf8"));
+    return resolve(latest.directory, "audit.json");
+}
+async function commandRun(args) {
+    const { options, configPath } = parseRunOptions(args);
+    const config = await loadConfig(configPath);
+    const { runAudit } = await import("./run.js");
+    await runAudit(config, options);
+}
+async function commandReport(args) {
+    const auditArg = args[0] ?? "";
+    if (args.length !== 1 || auditArg === "--help" || auditArg === "-h") {
+        writeError("Usage: audit0 report <path/to/audit.json>\n");
+        process.exitCode = args.length === 1 && (auditArg === "--help" || auditArg === "-h") ? 0 : 1;
+        return;
+    }
+    try {
+        const auditPath = resolve(auditArg);
+        const audit = JSON.parse(await readFile(auditPath, "utf8"));
+        const reportPath = await writeReport(audit, dirname(auditPath));
+        write(`${reportPath}\n`);
+    }
+    catch (error) {
+        writeError(`Could not generate report: ${error.message}\n`);
+        process.exitCode = 1;
+    }
+}
+async function commandArchive(args) {
+    if (args[0] === "--verify" || args[0] === "verify") {
+        const archiveArg = args[1];
+        if (!archiveArg) {
+            throw new AuditConfigError("invalid-config", "", "Usage: audit0 archive verify <audit.zip>");
+        }
+        const archivePath = resolve(archiveArg);
+        await readAuditBundle(archivePath);
+        write(`Verified ${archivePath}\n`);
+        return;
+    }
+    const auditPath = await resolveAuditPath(args[0]);
+    const outputPath = args[1] ? resolve(args[1]) : resolve(dirname(auditPath), "audit.zip");
+    write(`${await writeAuditArchive(auditPath, outputPath)}\n`);
+}
+async function commandAssets(args) {
+    const auditPath = await resolveAuditPath(args[0]);
+    const audit = JSON.parse(await readFile(auditPath, "utf8"));
+    audit.assets = await buildArtifactManifest(dirname(auditPath), audit);
+    await writeFile(auditPath, JSON.stringify(audit, null, 2));
+    write(`Manifested ${audit.assets.files.length} images in ${auditPath}\n`);
+    if (audit.assets.missing.length)
+        process.exitCode = 1;
+}
+async function commandValidate(args) {
+    if (!args[0])
+        throw new AuditConfigError("invalid-config", "", "Usage: audit0 validate <audit.json>");
+    const auditPath = resolve(args[0]);
+    const audit = JSON.parse(await readFile(auditPath, "utf8"));
+    await validateAuditDocument(audit);
+    write(`Valid ${auditPath}\n`);
+}
+export async function cli(argv) {
+    const [command, ...args] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        write(USAGE);
+        return;
+    }
+    switch (command) {
+        case "run":
+            await commandRun(args);
+            return;
+        case "inspect":
+            await commandInspect(args);
+            return;
+        case "report":
+            await commandReport(args);
+            return;
+        case "archive":
+            await commandArchive(args);
+            return;
+        case "assets":
+            await commandAssets(args);
+            return;
+        case "validate":
+            await commandValidate(args);
+            return;
+        default:
+            writeError(USAGE);
+            process.exitCode = 1;
+    }
+}
+export async function main() {
+    try {
+        await cli(process.argv.slice(2).filter((argument) => argument !== "--"));
+    }
+    catch (error) {
+        writeError(`${error.message}\n`);
+        process.exitCode = 1;
+    }
+}
+function isDirectInvocation() {
+    const invoked = process.argv[1];
+    if (!invoked)
+        return false;
+    try {
+        return realpathSync(invoked) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectInvocation()) {
+    await main();
+}

package/dist/config/defaults.d.ts

@@ -0,0 +1,2 @@
+import type { AuditSettings } from "./types.ts";
+export declare const defaultSettings: AuditSettings;

package/dist/config/defaults.js

@@ -0,0 +1,2 @@
+import { defaultSettings as engineDefaultSettings } from "../engine/settings.mjs";
+export const defaultSettings = engineDefaultSettings;

package/dist/config/define.d.ts

@@ -0,0 +1,2 @@
+import type { AuditConfig, AuditConfigInput } from "./types.ts";
+export declare function defineAudit(input: AuditConfigInput): AuditConfig;

package/dist/config/define.js

@@ -0,0 +1,112 @@
+import { defaultSettings } from "./defaults.js";
+import { AuditConfigError } from "./errors.js";
+import { normalizeMarker } from "./marker.js";
+import { auditConfigInputSchema } from "./schema.js";
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+    }
+    return value;
+}
+function assertUniqueIds(items, path) {
+    const seen = new Set();
+    for (const [index, item] of items.entries()) {
+        if (seen.has(item.id)) {
+            throw new AuditConfigError("duplicate-id", `${path}[${index}].id`, `duplicate id "${item.id}"`);
+        }
+        seen.add(item.id);
+    }
+}
+function assertMarkerNames(page, path) {
+    const known = new Set(Object.keys(page.markers));
+    const groups = [
+        ["shell", page.shell ?? []],
+        ["primary", page.primary],
+        ["complete", page.complete ?? []],
+    ];
+    for (const [field, names] of groups) {
+        for (const [index, name] of names.entries()) {
+            if (!known.has(name)) {
+                throw new AuditConfigError("unknown-marker", `${path}.${field}[${index}]`, `marker "${name}" is not defined in this page's markers`);
+            }
+        }
+    }
+    for (const [index, milestone] of (page.milestones ?? []).entries()) {
+        for (const [markerIndex, name] of milestone.markers.entries()) {
+            if (!known.has(name)) {
+                throw new AuditConfigError("unknown-marker", `${path}.milestones[${index}].markers[${markerIndex}]`, `marker "${name}" is not defined in this page's markers`);
+            }
+        }
+    }
+}
+function buildPage(page, path) {
+    assertMarkerNames(page, path);
+    assertUniqueIds((page.milestones ?? []).map((milestone, index) => ({ id: milestone.id, index })), `${path}.milestones`);
+    const markers = Object.fromEntries(Object.entries(page.markers).map(([name, rule]) => [
+        name,
+        normalizeMarker(rule),
+    ]));
+    return {
+        id: page.id,
+        path: page.path,
+        markers,
+        primary: page.primary,
+        shell: page.shell ?? [],
+        complete: page.complete ?? [],
+        milestones: (page.milestones ?? []).map((milestone) => ({
+            id: milestone.id,
+            label: milestone.label,
+            ...(milestone.description !== undefined ? { description: milestone.description } : {}),
+            markers: milestone.markers,
+            ...(milestone.gradeMetric !== undefined ? { gradeMetric: milestone.gradeMetric } : {}),
+        })),
+        feedbackIndicators: page.feedbackIndicators ?? [],
+        ...(page.fallback !== undefined ? { fallback: normalizeMarker(page.fallback) } : {}),
+    };
+}
+function mergeSettings(input) {
+    return {
+        repeats: input?.repeats ?? defaultSettings.repeats,
+        viewport: input?.viewport
+            ? { width: input.viewport.width, height: input.viewport.height }
+            : { ...defaultSettings.viewport },
+        sourceDwellMs: input?.sourceDwellMs ?? defaultSettings.sourceDwellMs,
+        preClickHoverMs: input?.preClickHoverMs ?? defaultSettings.preClickHoverMs,
+        pageObservationMs: input?.pageObservationMs ?? defaultSettings.pageObservationMs,
+        navigationObservationMs: input?.navigationObservationMs ?? defaultSettings.navigationObservationMs,
+    };
+}
+export function defineAudit(input) {
+    const parsed = auditConfigInputSchema.safeParse(input);
+    if (!parsed.success) {
+        const issue = parsed.error.issues[0];
+        throw new AuditConfigError("invalid-config", issue?.path.join(".") ?? "", issue?.message ?? "invalid audit config");
+    }
+    const config = parsed.data;
+    assertUniqueIds(config.pages, "pages");
+    const journeys = config.journeys ?? [];
+    assertUniqueIds(journeys, "journeys");
+    const pageIds = new Set(config.pages.map((page) => page.id));
+    for (const [index, journey] of journeys.entries()) {
+        for (const side of ["from", "to"]) {
+            if (!pageIds.has(journey[side])) {
+                throw new AuditConfigError("unknown-page", `journeys[${index}].${side}`, `page "${journey[side]}" is not defined in pages`);
+            }
+        }
+    }
+    const normalizedJourneys = journeys.map((journey) => ({
+        id: journey.id,
+        from: journey.from,
+        to: journey.to,
+        ...(journey.label !== undefined ? { label: journey.label } : {}),
+    }));
+    return deepFreeze({
+        origin: config.origin,
+        pages: config.pages.map((page, index) => buildPage(page, `pages[${index}]`)),
+        journeys: normalizedJourneys,
+        settings: mergeSettings(config.settings),
+    });
+}

package/dist/config/errors.d.ts

@@ -0,0 +1,6 @@
+export type AuditConfigErrorCode = "invalid-config" | "duplicate-id" | "unknown-page" | "unknown-marker";
+export declare class AuditConfigError extends Error {
+    readonly code: AuditConfigErrorCode;
+    readonly path: string;
+    constructor(code: AuditConfigErrorCode, path: string, message: string);
+}

package/dist/config/errors.js

@@ -0,0 +1,10 @@
+export class AuditConfigError extends Error {
+    code;
+    path;
+    constructor(code, path, message) {
+        super(path ? `${path}: ${message}` : message);
+        this.name = "AuditConfigError";
+        this.code = code;
+        this.path = path;
+    }
+}

package/dist/config/marker.d.ts

@@ -0,0 +1,3 @@
+import type { MarkerInput, MarkerOptions, MarkerRule } from "./types.ts";
+export declare function marker(selector: string, options?: MarkerOptions): MarkerInput;
+export declare function normalizeMarker(input: MarkerInput): MarkerRule;

package/dist/config/marker.js

@@ -0,0 +1,27 @@
+const DEFAULT_PATTERN_FLAGS = "i";
+export function marker(selector, options = {}) {
+    const rule = { selector };
+    if (options.min !== undefined)
+        rule.min = options.min;
+    if (options.text !== undefined)
+        rule.text = options.text;
+    if (options.pattern !== undefined)
+        rule.pattern = options.pattern;
+    if (options.contains !== undefined)
+        rule.contains = options.contains;
+    return rule;
+}
+function normalizePattern(pattern) {
+    if (typeof pattern === "string")
+        return { source: pattern, flags: DEFAULT_PATTERN_FLAGS };
+    return { source: pattern.source, flags: pattern.flags };
+}
+export function normalizeMarker(input) {
+    return {
+        selector: input.selector,
+        min: input.min ?? 1,
+        ...(input.text !== undefined ? { text: input.text } : {}),
+        ...(input.pattern !== undefined ? { pattern: normalizePattern(input.pattern) } : {}),
+        ...(input.contains !== undefined ? { contains: input.contains.map(normalizeMarker) } : {}),
+    };
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+import type { AuditConfigInput } from "./types.ts";
+export declare const auditConfigInputSchema: z.ZodType<AuditConfigInput>;

package/dist/config/schema.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+const markerInputSchema = z.lazy(() => z
+    .object({
+    selector: z.string().min(1),
+    min: z.number().int().positive().optional(),
+    text: z.string().optional(),
+    pattern: z.union([z.string(), z.instanceof(RegExp)]).optional(),
+    contains: z.array(markerInputSchema).optional(),
+})
+    .strict());
+const milestoneSchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    markers: z.array(z.string().min(1)).min(1),
+    gradeMetric: z.enum(["feedback", "content"]).optional(),
+})
+    .strict();
+const pageSchema = z
+    .object({
+    id: z.string().min(1),
+    path: z
+        .string()
+        .regex(/^\/[^?#]*$/, "must be a pathname starting with / without a query string or fragment; pages are matched against location.pathname"),
+    markers: z.record(z.string().min(1), markerInputSchema),
+    primary: z.array(z.string().min(1)).min(1),
+    shell: z.array(z.string().min(1)).optional(),
+    complete: z.array(z.string().min(1)).optional(),
+    milestones: z.array(milestoneSchema).optional(),
+    fallback: markerInputSchema.optional(),
+    feedbackIndicators: z.array(z.string().min(1)).optional(),
+})
+    .strict();
+const journeySchema = z
+    .object({
+    id: z.string().min(1),
+    from: z.string().min(1),
+    to: z.string().min(1),
+    label: z.string().optional(),
+})
+    .strict();
+const settingsSchema = z
+    .object({
+    repeats: z.number().int().min(1).max(20).optional(),
+    viewport: z
+        .object({
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+    })
+        .strict()
+        .optional(),
+    sourceDwellMs: z.number().int().nonnegative().optional(),
+    preClickHoverMs: z.number().int().nonnegative().optional(),
+    pageObservationMs: z.number().int().nonnegative().optional(),
+    navigationObservationMs: z.number().int().positive().optional(),
+})
+    .strict();
+export const auditConfigInputSchema = z
+    .object({
+    origin: z.url(),
+    pages: z.array(pageSchema).min(1),
+    journeys: z.array(journeySchema).optional(),
+    settings: settingsSchema.optional(),
+})
+    .strict();

package/dist/config/types.d.ts

@@ -0,0 +1,107 @@
+export interface MarkerPattern {
+    readonly source: string;
+    readonly flags: string;
+}
+export interface MarkerInput {
+    selector: string;
+    min?: number;
+    text?: string;
+    pattern?: string | RegExp;
+    contains?: MarkerInput[];
+}
+export interface MarkerOptions {
+    min?: number;
+    text?: string;
+    pattern?: string | RegExp;
+    contains?: MarkerInput[];
+}
+export interface MarkerRule {
+    readonly selector: string;
+    readonly min: number;
+    readonly text?: string;
+    readonly pattern?: MarkerPattern;
+    readonly contains?: readonly MarkerRule[];
+}
+export interface MilestoneInput {
+    id: string;
+    label: string;
+    description?: string;
+    markers: string[];
+    gradeMetric?: "feedback" | "content";
+}
+export interface MilestoneSpec {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly markers: readonly string[];
+    readonly gradeMetric?: "feedback" | "content";
+}
+export interface PageInput {
+    id: string;
+    path: string;
+    markers: Record<string, MarkerInput>;
+    primary: string[];
+    shell?: string[];
+    complete?: string[];
+    milestones?: MilestoneInput[];
+    fallback?: MarkerInput;
+    feedbackIndicators?: string[];
+}
+export interface PageSpec {
+    readonly id: string;
+    readonly path: string;
+    readonly markers: Readonly<Record<string, MarkerRule>>;
+    readonly primary: readonly string[];
+    readonly shell: readonly string[];
+    readonly complete: readonly string[];
+    readonly milestones: readonly MilestoneSpec[];
+    readonly feedbackIndicators: readonly string[];
+    readonly fallback?: MarkerRule;
+}
+export interface JourneyInput {
+    id: string;
+    from: string;
+    to: string;
+    label?: string;
+}
+export interface JourneySpec {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    readonly label?: string;
+}
+export interface Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+export interface AuditSettingsInput {
+    repeats?: number;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    sourceDwellMs?: number;
+    preClickHoverMs?: number;
+    pageObservationMs?: number;
+    navigationObservationMs?: number;
+}
+export interface AuditSettings {
+    readonly repeats: number;
+    readonly viewport: Viewport;
+    readonly sourceDwellMs: number;
+    readonly preClickHoverMs: number;
+    readonly pageObservationMs: number;
+    readonly navigationObservationMs: number;
+}
+export interface AuditConfigInput {
+    origin: string;
+    pages: PageInput[];
+    journeys?: JourneyInput[];
+    settings?: AuditSettingsInput;
+}
+export interface AuditConfig {
+    readonly origin: string;
+    readonly pages: readonly PageSpec[];
+    readonly journeys: readonly JourneySpec[];
+    readonly settings: AuditSettings;
+}

package/dist/config/types.js

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

package/dist/engine/artifacts.d.mts

@@ -0,0 +1,11 @@
+export declare function portableArtifactPath(path: any): {
+    path: string;
+    mediaType: any;
+} | null;
+export declare function referencedArtifacts(audit: any): any[];
+export declare function buildArtifactManifest(directory: any, audit: any): Promise<{
+    version: number;
+    pathSemantics: string;
+    files: any[];
+    missing: any[];
+}>;