vagejs 0.0.0-stage → 0.2.0

package/dist/audit/lighthouse.js

@@ -0,0 +1,48 @@
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { VageError } from "../core/errors.js";
+import { labReport } from "./remote.js";
+/**
+ * Loads Lighthouse from the user's project. It is an optional peer dependency
+ * (large, and needs Chrome), so it is never required for build or check.
+ */
+async function loadLighthouse(root) {
+    const require = createRequire(pathToFileURL(`${root}/package.json`));
+    let entry;
+    try {
+        entry = require.resolve("lighthouse");
+    }
+    catch {
+        throw new VageError('Lighthouse is not installed. Run "npm install --save-dev lighthouse" (requires Chrome), or audit without --lighthouse.');
+    }
+    const mod = await import(pathToFileURL(entry).href);
+    // chrome-launcher is a Lighthouse dependency; resolve it from there.
+    const launcher = await import(pathToFileURL(createRequire(entry).resolve("chrome-launcher")).href);
+    return { lighthouse: mod.default, desktopConfig: mod.desktopConfig, launcher };
+}
+/** Runs Lighthouse (lab) against already-served URLs. */
+export async function runLighthouse(root, urls, strategies) {
+    const { lighthouse, desktopConfig, launcher } = await loadLighthouse(root);
+    let chrome;
+    try {
+        chrome = await launcher.launch({ chromeFlags: ["--headless=new"] });
+    }
+    catch (err) {
+        throw new VageError(`Could not start Chrome for Lighthouse: ${err.message}. Install Chrome or set CHROME_PATH.`);
+    }
+    try {
+        const reports = [];
+        for (const url of urls) {
+            for (const strategy of strategies) {
+                const result = await lighthouse(url, { port: chrome.port, output: "json", logLevel: "error", onlyCategories: ["performance", "accessibility", "seo", "best-practices"] }, strategy === "desktop" ? desktopConfig : undefined);
+                if (!result)
+                    throw new VageError(`Lighthouse returned no result for ${url}.`);
+                reports.push(labReport(result.lhr, "lighthouse", url, strategy));
+            }
+        }
+        return reports;
+    }
+    finally {
+        chrome.kill();
+    }
+}

package/dist/audit/remote.d.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { redact, type HttpOptions } from "../integrations/http.js";
+import { type Rating, type VitalName } from "./vitals.js";
+export type Strategy = "mobile" | "desktop";
+export type RemoteOptions = HttpOptions;
+export { redact };
+declare const CATEGORY_IDS: readonly ["performance", "accessibility", "seo", "best-practices"];
+declare const psiSchema: z.ZodObject<{
+    lighthouseResult: z.ZodObject<{
+        lighthouseVersion: z.ZodString;
+        fetchTime: z.ZodString;
+        finalDisplayedUrl: z.ZodOptional<z.ZodString>;
+        categories: z.ZodRecord<z.ZodString, z.ZodObject<{
+            score: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        audits: z.ZodRecord<z.ZodString, z.ZodObject<{
+            title: z.ZodString;
+            score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            numericValue: z.ZodOptional<z.ZodNumber>;
+            displayValue: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export interface LabReport {
+    source: "pagespeed-insights" | "lighthouse";
+    url: string;
+    strategy: Strategy;
+    fetchTime: string;
+    toolVersion: string;
+    /** 0-100, or null when the tool returned no score. */
+    scores: Record<(typeof CATEGORY_IDS)[number], number | null>;
+    metrics: {
+        lcpMs?: number;
+        cls?: number;
+        tbtMs?: number;
+        fcpMs?: number;
+        speedIndexMs?: number;
+    };
+    /** Lowest-scoring audits, most impactful first. */
+    opportunities: {
+        id: string;
+        title: string;
+        displayValue?: string;
+    }[];
+}
+/** Normalizes a Lighthouse result (from PSI or a local run). */
+export declare function labReport(lhr: z.infer<typeof psiSchema>["lighthouseResult"], source: LabReport["source"], url: string, strategy: Strategy): LabReport;
+export declare function pageSpeed(url: string, strategy: Strategy, key: string | undefined, opts?: RemoteOptions): Promise<LabReport>;
+export interface FieldReport {
+    source: "crux";
+    /** "url" when page-level data exists, otherwise "origin". */
+    scope: "url" | "origin";
+    formFactor: "PHONE" | "DESKTOP";
+    collectionPeriod?: string;
+    metrics: Partial<Record<VitalName, {
+        p75: number;
+        rating: Rating;
+    }>>;
+}
+/**
+ * Queries the CrUX API for the page, falling back to the origin. Returns
+ * undefined when neither has data. A 404 is treated as "no data"; the API
+ * docs do not specify this response, so it is an observed-behavior assumption.
+ */
+export declare function cruxField(url: string, strategy: Strategy, key: string, opts?: RemoteOptions): Promise<FieldReport | undefined>;

package/dist/audit/remote.js

@@ -0,0 +1,123 @@
+import { z } from "zod";
+import { VageError } from "../core/errors.js";
+import { apiError, redact, requestWithRetry } from "../integrations/http.js";
+import { rate } from "./vitals.js";
+const PSI_ENDPOINT = "https://www.googleapis.com/pagespeedonline/v5/runPagespeed";
+const CRUX_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+const KEY_HINTS = {
+    400: "Check the URL is public and the API key has this API enabled.",
+    403: "Check the URL is public and the API key has this API enabled.",
+    429: "Rate limited: wait and retry, or use an API key with quota.",
+};
+/** The API key goes in the x-goog-api-key header, never in the URL. */
+function withKey(init, key) {
+    return { ...init, headers: { ...init.headers, ...(key ? { "x-goog-api-key": key } : {}) } };
+}
+export { redact };
+// ---------------------------------------------------------------- PageSpeed Insights (lab)
+const CATEGORY_IDS = ["performance", "accessibility", "seo", "best-practices"];
+const psiSchema = z.object({
+    lighthouseResult: z.object({
+        lighthouseVersion: z.string(),
+        fetchTime: z.string(),
+        finalDisplayedUrl: z.string().optional(),
+        categories: z.record(z.string(), z.object({ score: z.number().nullable() })),
+        audits: z.record(z.string(), z.object({ title: z.string(), score: z.number().nullable().optional(), numericValue: z.number().optional(), displayValue: z.string().optional() })),
+    }),
+});
+/** Normalizes a Lighthouse result (from PSI or a local run). */
+export function labReport(lhr, source, url, strategy) {
+    const score = (id) => {
+        const s = lhr.categories[id]?.score;
+        return s === null || s === undefined ? null : Math.round(s * 100);
+    };
+    const num = (id) => lhr.audits[id]?.numericValue;
+    const opportunities = Object.entries(lhr.audits)
+        .filter(([, a]) => typeof a.score === "number" && a.score < 0.9 && a.displayValue)
+        .sort(([, a], [, b]) => (a.score ?? 1) - (b.score ?? 1))
+        .slice(0, 8)
+        .map(([id, a]) => ({ id, title: a.title, displayValue: a.displayValue }));
+    return {
+        source,
+        url,
+        strategy,
+        fetchTime: lhr.fetchTime,
+        toolVersion: `lighthouse ${lhr.lighthouseVersion}`,
+        scores: {
+            performance: score("performance"),
+            accessibility: score("accessibility"),
+            seo: score("seo"),
+            "best-practices": score("best-practices"),
+        },
+        metrics: {
+            lcpMs: num("largest-contentful-paint"),
+            cls: num("cumulative-layout-shift"),
+            tbtMs: num("total-blocking-time"),
+            fcpMs: num("first-contentful-paint"),
+            speedIndexMs: num("speed-index"),
+        },
+        opportunities,
+    };
+}
+export async function pageSpeed(url, strategy, key, opts = {}) {
+    const params = new URLSearchParams({ url, strategy: strategy.toUpperCase() });
+    for (const c of CATEGORY_IDS)
+        params.append("category", c.toUpperCase().replace("-", "_"));
+    const res = await requestWithRetry("PageSpeed Insights", `${PSI_ENDPOINT}?${params}`, withKey({ method: "GET" }, key), [key], opts);
+    if (!res.ok)
+        throw await apiError("PageSpeed Insights", res, [key], KEY_HINTS);
+    const parsed = psiSchema.safeParse(await res.json().catch(() => undefined));
+    if (!parsed.success)
+        throw new VageError("PageSpeed Insights returned an unexpected response (no lighthouseResult).");
+    return labReport(parsed.data.lighthouseResult, "pagespeed-insights", url, strategy);
+}
+// ---------------------------------------------------------------- CrUX (field)
+const cruxSchema = z.object({
+    record: z.object({
+        metrics: z.record(z.string(), z.object({ percentiles: z.object({ p75: z.union([z.number(), z.string()]) }) })),
+        collectionPeriod: z
+            .object({
+            firstDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+            lastDate: z.object({ year: z.number(), month: z.number(), day: z.number() }),
+        })
+            .optional(),
+    }),
+});
+const CRUX_METRICS = {
+    largest_contentful_paint: "lcp",
+    interaction_to_next_paint: "inp",
+    cumulative_layout_shift: "cls",
+};
+/**
+ * Queries the CrUX API for the page, falling back to the origin. Returns
+ * undefined when neither has data. A 404 is treated as "no data"; the API
+ * docs do not specify this response, so it is an observed-behavior assumption.
+ */
+export async function cruxField(url, strategy, key, opts = {}) {
+    const formFactor = strategy === "mobile" ? "PHONE" : "DESKTOP";
+    for (const scope of ["url", "origin"]) {
+        const body = { [scope]: scope === "url" ? url : new URL(url).origin, formFactor, metrics: Object.keys(CRUX_METRICS) };
+        const init = withKey({ method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, key);
+        const res = await requestWithRetry("CrUX API", CRUX_ENDPOINT, init, [key], opts);
+        if (res.status === 404)
+            continue;
+        if (!res.ok)
+            throw await apiError("CrUX API", res, [key], KEY_HINTS);
+        const parsed = cruxSchema.safeParse(await res.json().catch(() => undefined));
+        if (!parsed.success)
+            throw new VageError("CrUX API returned an unexpected response (no record.metrics).");
+        const metrics = {};
+        for (const [apiName, name] of Object.entries(CRUX_METRICS)) {
+            const raw = parsed.data.record.metrics[apiName]?.percentiles.p75;
+            if (raw === undefined)
+                continue;
+            const p75 = Number(raw); // CLS is a string-encoded double
+            if (Number.isFinite(p75))
+                metrics[name] = { p75, rating: rate(name, p75) };
+        }
+        const period = parsed.data.record.collectionPeriod;
+        const date = (d) => `${d.year}-${String(d.month).padStart(2, "0")}-${String(d.day).padStart(2, "0")}`;
+        return { source: "crux", scope, formFactor, metrics, collectionPeriod: period && `${date(period.firstDate)} to ${date(period.lastDate)}` };
+    }
+    return undefined;
+}

package/dist/audit/vitals.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Core Web Vitals thresholds, assessed at the 75th percentile of real-user
+ * page loads (rule pack "vitals.thresholds", source: https://web.dev/articles/vitals).
+ */
+export declare const VITALS: {
+    readonly lcp: {
+        readonly good: number;
+        readonly poor: number;
+        readonly label: "LCP";
+        readonly unit: "ms";
+    };
+    readonly inp: {
+        readonly good: number;
+        readonly poor: number;
+        readonly label: "INP";
+        readonly unit: "ms";
+    };
+    readonly cls: {
+        readonly good: number;
+        readonly poor: number;
+        readonly label: "CLS";
+        readonly unit: "";
+    };
+};
+export type VitalName = keyof typeof VITALS;
+export type Rating = "good" | "needs-improvement" | "poor";
+export declare function rate(metric: VitalName, p75: number): Rating;
+export declare const LAB_VS_FIELD: string;

package/dist/audit/vitals.js

@@ -0,0 +1,18 @@
+import { ruleData } from "../guidelines/pack.js";
+const T = ruleData("vitals.thresholds");
+/**
+ * Core Web Vitals thresholds, assessed at the 75th percentile of real-user
+ * page loads (rule pack "vitals.thresholds", source: https://web.dev/articles/vitals).
+ */
+export const VITALS = {
+    lcp: { label: "LCP", unit: "ms", ...T.lcp },
+    inp: { label: "INP", unit: "ms", ...T.inp },
+    cls: { label: "CLS", unit: "", ...T.cls },
+};
+export function rate(metric, p75) {
+    const t = VITALS[metric];
+    return p75 <= t.good ? "good" : p75 <= t.poor ? "needs-improvement" : "poor";
+}
+export const LAB_VS_FIELD = "Lab results (Lighthouse/PageSpeed) are a single simulated load and vary between runs. " +
+    "Field data (CrUX) reflects real Chrome users at the 75th percentile over 28 days and is " +
+    "unavailable for pages or sites without enough traffic. Google's Core Web Vitals assessment uses field data.";

package/dist/checks/check.d.ts

@@ -0,0 +1,31 @@
+import { type SiteModel } from "../core/site.js";
+export type Severity = "error" | "warning";
+export interface Finding {
+    rule: string;
+    severity: Severity;
+    message: string;
+    /** Route of the page the finding is about, if any. */
+    page?: string;
+    /** Source file relative to the project root, if any. */
+    source?: string;
+    /** Official documentation backing the rule, where one exists. */
+    docs?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    errors: number;
+    warnings: number;
+    pagesChecked: number;
+    findings: Finding[];
+}
+/** Paths of frontmatter values that came out empty (null), e.g. "faq.items[3].Claude and other AI search?". */
+export declare function emptyValues(value: unknown, at?: string): string[];
+/**
+ * Static checks on the rendered site (nothing is written to disk).
+ * Passing checks mean the output is technically sound; they do not guarantee
+ * indexing, rankings, rich results or AI citations.
+ */
+export declare function check(root: string, options?: {
+    strict?: boolean;
+}): Promise<CheckResult>;
+export declare function checkSite(root: string, model: SiteModel): Finding[];