@salesforce/storefront-next-dev 1.4.0 → 1.5.0-alpha.0

package/dist/live.js

@@ -0,0 +1,277 @@
+import path from "node:path";
+import { z } from "zod";
+import { decode } from "@jridgewell/sourcemap-codec";
+import { ImportType, init, parse } from "es-module-lexer";
+
+//#region src/audit/bundle/parse.ts
+const visualizerSchema = z.object({
+	version: z.number(),
+	nodeParts: z.record(z.string(), z.object({
+		renderedLength: z.number(),
+		metaUid: z.string()
+	}).passthrough()),
+	nodeMetas: z.record(z.string(), z.object({
+		id: z.string(),
+		moduleParts: z.record(z.string(), z.string()),
+		imported: z.array(z.object({
+			uid: z.string(),
+			dynamic: z.boolean().optional()
+		}).passthrough()),
+		isEntry: z.boolean().nullable().optional()
+	}).passthrough())
+}).passthrough();
+/** Data versions this parser has been checked against. */
+const VISUALIZER_VERSIONS = new Set([2]);
+/** Rollup's virtual modules (`\0vite/preload-helper`) have no file; they're bundler runtime. */
+const isVirtual = (id) => id.startsWith("\0") && !id.slice(1).startsWith("/");
+/**
+* The visualizer writes ids relative to the project root when they're inside it (`/src/root.tsx`) and absolute
+* otherwise (a hoisted `node_modules`). An id is relative when its first segment is an entry of the project root.
+*/
+function moduleIdResolver(projectRoot, rootEntries) {
+	return (raw) => {
+		const id = (raw.startsWith("\0") ? raw.slice(1) : raw).replace(/\?.*$/, "");
+		const first = id.split("/")[1] ?? "";
+		return id.startsWith("/") && rootEntries.has(first) ? path.join(projectRoot, id) : path.resolve(id);
+	};
+}
+function parseVisualizerHtml(html, resolveId) {
+	const match = html.match(/^\s*const data = (\{.*\});\s*$/m);
+	if (!match) throw new Error("The visualizer report has no embedded `const data = {…}`.");
+	const data = visualizerSchema.parse(JSON.parse(match[1]));
+	if (!VISUALIZER_VERSIONS.has(data.version)) throw new Error(`Unsupported visualizer data version ${data.version}.`);
+	const graph = /* @__PURE__ */ new Map();
+	for (const meta of Object.values(data.nodeMetas)) {
+		if (isVirtual(meta.id)) continue;
+		const id = resolveId(meta.id);
+		const node = graph.get(id) ?? {
+			id,
+			static: /* @__PURE__ */ new Set(),
+			dynamic: /* @__PURE__ */ new Set(),
+			rendered: 0,
+			entry: false,
+			chunks: /* @__PURE__ */ new Set()
+		};
+		node.entry ||= meta.isEntry === true;
+		for (const [chunk, partUid] of Object.entries(meta.moduleParts)) {
+			const part = data.nodeParts[partUid];
+			if (!part) throw new Error(`Visualizer module ${meta.id} names an unknown part ${partUid}.`);
+			node.chunks.add(chunk);
+			node.rendered += part.renderedLength;
+		}
+		for (const edge of meta.imported) {
+			const target = data.nodeMetas[edge.uid];
+			if (!target || isVirtual(target.id)) continue;
+			const targetId = resolveId(target.id);
+			if (targetId !== id) (edge.dynamic ? node.dynamic : node.static).add(targetId);
+		}
+		graph.set(id, node);
+	}
+	for (const node of graph.values()) for (const target of node.dynamic) node.static.delete(target);
+	return graph;
+}
+const sourceMapSchema = z.object({
+	sources: z.array(z.string().nullable()),
+	sourceRoot: z.string().optional(),
+	mappings: z.string()
+}).passthrough();
+const PRELOAD_LIST_PREFIX = "const __vite__mapDeps=";
+const ROUTER_MANIFEST_PREFIX = "window.__reactRouterManifest=";
+const lexerReady = init;
+/** `code` and `map` are the chunk and its `.map` (absent when the build wrote none); `assetsDir` resolves map sources. */
+function parseChunk(file, code, map, assetsDir) {
+	const bytes = Buffer.byteLength(code);
+	const routerManifest = code.startsWith(ROUTER_MANIFEST_PREFIX);
+	const imports = /* @__PURE__ */ new Set();
+	const dynamicImports = /* @__PURE__ */ new Set();
+	if (!routerManifest) for (const item of parse(code)[0]) {
+		if (item.t === ImportType.ImportMeta || !item.n?.startsWith("./")) continue;
+		(item.t === ImportType.Dynamic ? dynamicImports : imports).add(item.n.slice(2));
+	}
+	const lines = code.split("\n");
+	const preloadList = lines[0].startsWith(PRELOAD_LIST_PREFIX) ? Buffer.byteLength(lines[0]) + (lines.length > 1 ? 1 : 0) : 0;
+	const chunk = {
+		file,
+		bytes,
+		modules: /* @__PURE__ */ new Map(),
+		preloadList,
+		unattributed: bytes - preloadList,
+		hasMap: false,
+		routerManifest,
+		imports: [...imports],
+		dynamicImports: [...dynamicImports].filter((item) => !imports.has(item))
+	};
+	if (routerManifest || map === void 0) return chunk;
+	const parsed = sourceMapSchema.parse(JSON.parse(map));
+	const sourceBase = path.resolve(assetsDir, parsed.sourceRoot ?? "");
+	const sources = parsed.sources.map((source) => source === null || source.includes("\0") ? null : path.resolve(sourceBase, source.replace(/\?.*$/, "")));
+	const decoded = decode(parsed.mappings);
+	let unattributed = 0;
+	const add = (source, length) => {
+		const id = source === void 0 ? null : sources[source];
+		if (id) chunk.modules.set(id, (chunk.modules.get(id) ?? 0) + length);
+		else unattributed += length;
+	};
+	lines.forEach((line, index) => {
+		const newline = index < lines.length - 1 ? 1 : 0;
+		if (index === 0 && preloadList) return;
+		unattributed += newline;
+		const segments = decoded[index] ?? [];
+		if (!segments.length) {
+			unattributed += Buffer.byteLength(line);
+			return;
+		}
+		unattributed += Buffer.byteLength(line.slice(0, segments[0][0]));
+		segments.forEach((segment, k) => {
+			const end = k + 1 < segments.length ? segments[k + 1][0] : line.length;
+			add(segment.length >= 4 ? segment[1] : void 0, Buffer.byteLength(line.slice(segment[0], end)));
+		});
+	});
+	chunk.hasMap = true;
+	chunk.unattributed = unattributed;
+	return chunk;
+}
+const manifestRouteSchema = z.object({
+	id: z.string(),
+	parentId: z.string().optional(),
+	path: z.string().optional(),
+	index: z.boolean().optional(),
+	module: z.string(),
+	imports: z.array(z.string()).optional()
+}).passthrough();
+const routerManifestSchema = z.object({
+	entry: z.object({
+		module: z.string(),
+		imports: z.array(z.string())
+	}).passthrough(),
+	routes: z.record(z.string(), manifestRouteSchema)
+}).passthrough();
+/** A chunk URL as the chunk's file name, the key every source here shares. */
+const assetName = (url) => url.replace(/[?#].*$/, "").split("/").at(-1) ?? url;
+/**
+* Parses `window.__reactRouterManifest={…}`. React Router writes JSON; the storefront-next SDK replaces each URL
+* with `(window._BUNDLE_PATH || "/") + "assets/x.js"`, which is folded back to a string. Module URLs become file names.
+*/
+function parseRouterManifest(code) {
+	if (!code.startsWith(ROUTER_MANIFEST_PREFIX)) throw new Error("Not a React Router manifest chunk.");
+	const json = code.slice(29).trim().replace(/;$/, "").replace(/\(\s*window\._BUNDLE_PATH\s*\|\|\s*"[^"]*"\s*\)\s*\+\s*"/g, "\"");
+	const manifest = routerManifestSchema.parse(JSON.parse(json));
+	manifest.entry.module = assetName(manifest.entry.module);
+	manifest.entry.imports = manifest.entry.imports.map(assetName);
+	for (const route of Object.values(manifest.routes)) {
+		route.module = assetName(route.module);
+		if (route.imports) route.imports = route.imports.map(assetName);
+	}
+	return manifest;
+}
+/**
+* React Router's `<Scripts>` renders an inline module that imports the matched routes and names them:
+* `import * as route0 from "…/root-x.js"; … window.__reactRouterRouteModules = {"root":route0,…}; import("…/entry.client-y.js");`.
+* That is the page's route branch, from the deployed site itself. Undefined when the script isn't this one.
+*/
+function parseRouteModulesScript(code) {
+	const assignment = code.match(/window\.__reactRouterRouteModules\s*=\s*\{([^}]*)\}/);
+	if (!assignment || assignment.index === void 0) return void 0;
+	const files = new Map([...code.matchAll(/import\s*\*\s*as\s+(\w+)\s+from\s*"([^"]+)"/g)].map((item) => [item[1], assetName(item[2])]));
+	const routes = [...assignment[1].matchAll(/"([^"]+)"\s*:\s*(\w+)/g)].flatMap((item) => {
+		const file = files.get(item[2]);
+		return file ? [{
+			id: item[1],
+			file
+		}] : [];
+	});
+	if (!routes.length) return void 0;
+	const entry = code.slice(assignment.index).match(/import\(\s*"([^"]+)"\s*\)/)?.[1];
+	return {
+		routes,
+		...entry ? { entry: assetName(entry) } : {}
+	};
+}
+
+//#endregion
+//#region src/audit/bundle/live.ts
+const CELL = {
+	formFactor: "mobile",
+	cacheState: "cold"
+};
+/** Storefront Next serves the app's build from this path on Managed Runtime. */
+const BUNDLE_PATH = "/mobify/bundle/";
+const lcpSummarySchema = z.object({ cells: z.array(z.object({
+	formFactor: z.string(),
+	cacheState: z.string(),
+	median: z.object({ runId: z.string() }).passthrough().nullable().optional()
+}).passthrough()) }).passthrough();
+const requestSchema = z.object({
+	url: z.string(),
+	resourceType: z.string().optional(),
+	statusCode: z.number().optional(),
+	resourceSize: z.number().optional(),
+	transferSize: z.number().optional(),
+	networkRequestTime: z.number().optional()
+}).passthrough();
+const lhrSchema = z.object({ audits: z.object({
+	"network-requests": z.object({ details: z.object({ items: z.array(requestSchema) }).passthrough().optional() }).passthrough().optional(),
+	metrics: z.object({ details: z.object({ items: z.array(z.object({ observedLoad: z.number().optional() }).passthrough()) }).passthrough().optional() }).passthrough().optional()
+}).passthrough() }).passthrough();
+const scriptsIndexSchema = z.object({ observations: z.array(z.object({
+	runId: z.string(),
+	url: z.string(),
+	body: z.object({ sha256: z.string() }).passthrough().nullable().optional()
+}).passthrough()) }).passthrough();
+/** A first-party script: served from the storefront's bundle path. */
+function isFirstParty(url) {
+	try {
+		return new URL(url).pathname.includes(BUNDLE_PATH);
+	} catch {
+		return false;
+	}
+}
+/** The page's median mobile cold-cache run's first-party scripts, or why they can't be read. */
+async function readLivePage(playhouse, page) {
+	const runId = (await playhouse.readJson(page, "summary-lcp.json", lcpSummarySchema))?.cells.find((cell) => cell.formFactor === CELL.formFactor && cell.cacheState === CELL.cacheState)?.median?.runId;
+	if (!runId) return { reason: "summary-lcp.json has no mobile cold-cache median run." };
+	const lighthouseArtifact = `runs/${runId}/lhr.json`;
+	const lhr = await playhouse.readJson(page, lighthouseArtifact, lhrSchema);
+	const items = lhr?.audits["network-requests"]?.details?.items;
+	if (!items) return { reason: `${lighthouseArtifact} has no network-requests audit.` };
+	const load = lhr.audits.metrics?.details?.items[0]?.observedLoad;
+	const observedLoadMs = typeof load === "number" && load > 0 ? load : null;
+	const scripts = items.flatMap((request, item) => {
+		if (request.resourceType !== "Script" || (request.statusCode ?? 200) >= 400 || !isFirstParty(request.url)) return [];
+		const startMs = request.networkRequestTime ?? null;
+		return [{
+			url: request.url,
+			file: assetName(request.url),
+			item,
+			decodedBytes: request.resourceSize ?? 0,
+			transferBytes: request.transferSize ?? 0,
+			startMs,
+			beforeLoad: observedLoadMs === null || startMs !== null && startMs <= observedLoadMs
+		}];
+	});
+	const rendered = await readRenderedRoutes(playhouse, page, runId);
+	return {
+		page,
+		runId,
+		lighthouseArtifact,
+		observedLoadMs,
+		scripts,
+		...rendered ? { rendered } : {}
+	};
+}
+/** The route branch from React Router's inline script in the run's HTML, when Playhouse archived it. */
+async function readRenderedRoutes(playhouse, page, runId) {
+	const index = await playhouse.readJson(page, "scripts/index.json", scriptsIndexSchema);
+	const seen = /* @__PURE__ */ new Set();
+	for (const observation of index?.observations ?? []) {
+		const sha = observation.body?.sha256;
+		if (observation.runId !== runId || !sha || !/^[a-f0-9]{64}$/.test(sha) || seen.has(sha) || /\.m?js(?:[?#]|$)/.test(observation.url)) continue;
+		seen.add(sha);
+		const code = await playhouse.readText(page, `scripts/${sha}.js`);
+		const rendered = code === void 0 ? void 0 : parseRouteModulesScript(code);
+		if (rendered) return rendered;
+	}
+}
+
+//#endregion
+export { parseRouterManifest as a, parseChunk as i, lexerReady as n, parseVisualizerHtml as o, moduleIdResolver as r, readLivePage as t };

package/dist/logger.js

@@ -1,11 +1,8 @@
+import { t as version } from "./package.js";
 import os from "os";
 import chalk from "chalk";
 import { createRequire } from "module";
 
-//#region package.json
-var version = "1.4.0";
-
-//#endregion
 //#region src/utils/logger.ts
 /**
 * Get the local network IPv4 address

package/dist/measured-run.js

@@ -0,0 +1,91 @@
+//#region src/audit/measured-run.ts
+const object = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+const list = (value) => Array.isArray(value) ? value : [];
+/** Playhouse writes 0 for a metric it could not measure. A rendered page always has a positive LCP, so a run without one measured nothing. */
+function isMeasured(run) {
+	const lcp = object(run)?.lcp;
+	return typeof lcp === "number" && Number.isFinite(lcp) && lcp > 0;
+}
+/** A run row that has an LCP but not a positive one: Playhouse could not measure it. A row without an LCP can't say. */
+const isFailedRow = (row) => typeof object(row)?.lcp === "number" && !isMeasured(row);
+function median(values) {
+	const sorted = values.slice().sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 0 ? ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2 : sorted[mid] ?? 0;
+}
+/**
+* A summary.json cell's representative run, leaving out runs Playhouse could not measure.
+* Playhouse picks the run whose LCP is closest to the median of every run, zeros included, so one failed run
+* can move the pick. When a run failed, this repeats Playhouse's selection (closest to the median, ties to the
+* earlier run) over the measured runs only; otherwise it returns Playhouse's own `medianRun`.
+* Undefined when the cell is missing or no run was measured.
+* Playhouse versions that retry and skip a run without an LCP never write these zeros, but archives from
+* older versions still contain them.
+*/
+function measuredRun(summary, cellIndex, eligible = isMeasured) {
+	const root = object(summary);
+	const cell = object(list(root?.cells)[cellIndex]);
+	if (!cell) return void 0;
+	const rows = list(root?.runs).map((entry, index) => ({
+		entry: object(entry),
+		index
+	})).flatMap(({ entry, index }) => {
+		const row = object(entry?.row);
+		return row && typeof row.lcp === "number" && entry?.formFactor === cell.formFactor && entry?.cacheState === cell.cacheState ? [{
+			row,
+			index
+		}] : [];
+	});
+	const measured = rows.filter(({ row }) => eligible(row));
+	const medianRun = object(cell.medianRun);
+	if (medianRun && eligible(medianRun) && measured.length === rows.length) return {
+		run: medianRun,
+		pointer: `/cells/${cellIndex}/medianRun`,
+		unmeasuredRuns: 0
+	};
+	if (!measured.length) return void 0;
+	const lcp = (item) => item.row.lcp;
+	const target = median(measured.map(lcp));
+	const closest = measured.reduce((best, item) => Math.abs(lcp(item) - target) < Math.abs(lcp(best) - target) ? item : best);
+	return {
+		run: closest.row,
+		pointer: `/runs/${closest.index}/row`,
+		unmeasuredRuns: rows.length - measured.length
+	};
+}
+/** The mobile/cold (else first) cell's score and core metrics for the live progress screen. Returns no score
+* when the artifact is absent or nothing was measured, so the dashboard never shows a fabricated number. */
+function perfFromSummary(summary) {
+	const mobileCold = list(object(summary)?.cells).findIndex((entry) => object(entry)?.formFactor === "mobile" && object(entry)?.cacheState === "cold");
+	const run = measuredRun(summary, mobileCold >= 0 ? mobileCold : 0)?.run;
+	if (!run) return { metrics: [] };
+	const seconds = (value) => `${(value / 1e3).toFixed(1)}s`;
+	const metrics = [];
+	if (typeof run.lcp === "number") metrics.push({
+		key: "LCP",
+		value: seconds(run.lcp),
+		bad: run.lcp > 2500
+	});
+	if (typeof run.tbt === "number") metrics.push({
+		key: "TBT",
+		value: `${Math.round(run.tbt)}ms`,
+		bad: run.tbt > 200
+	});
+	if (typeof run.cls === "number") metrics.push({
+		key: "CLS",
+		value: run.cls.toFixed(2),
+		bad: run.cls > .1
+	});
+	if (typeof run.ttfb === "number") metrics.push({
+		key: "TTFB",
+		value: seconds(run.ttfb),
+		bad: run.ttfb > 800
+	});
+	return {
+		score: typeof run.score === "number" ? run.score : void 0,
+		metrics
+	};
+}
+
+//#endregion
+export { perfFromSummary as i, isMeasured as n, measuredRun as r, isFailedRow as t };

package/dist/metric-budget.js

@@ -0,0 +1,125 @@
+import { n as isMeasured, r as measuredRun, t as isFailedRow } from "./measured-run.js";
+import { z } from "zod";
+
+//#region src/audit/rule-helpers/metric-budget.ts
+/** Budgets are checked against the mobile cold-cache median, the cell the dashboard leads with. */
+const CELL = {
+	formFactor: "mobile",
+	cacheState: "cold"
+};
+const summarySchema = z.object({
+	cells: z.array(z.object({
+		formFactor: z.string(),
+		cacheState: z.string(),
+		medianRun: z.record(z.string(), z.unknown())
+	}).passthrough()),
+	runs: z.array(z.object({
+		formFactor: z.string(),
+		cacheState: z.string(),
+		row: z.record(z.string(), z.unknown()).optional()
+	}).passthrough()).optional().default([])
+}).passthrough();
+const dataSchema = z.object({
+	metric: z.string(),
+	threshold: z.number(),
+	cell: z.string(),
+	pages: z.array(z.object({
+		page: z.string(),
+		value: z.number(),
+		threshold: z.number(),
+		runs: z.array(z.number()),
+		unmeasuredRuns: z.number()
+	}).strict()),
+	skipped: z.array(z.object({
+		page: z.string(),
+		reason: z.string()
+	}).strict())
+}).strict();
+const isCell = (cell) => cell.formFactor === CELL.formFactor && cell.cacheState === CELL.cacheState;
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+/** A rule script that passes when every page's mobile/cold median is at or under the threshold. */
+function metricBudget(budget) {
+	return async ({ pages, playhouse }) => {
+		const measured = [];
+		const skipped = [];
+		const evidence = [];
+		for (const page of pages) {
+			const summary = await playhouse.readJson(page.label, "summary.json", summarySchema);
+			const index = summary?.cells.findIndex(isCell) ?? -1;
+			if (index < 0) {
+				skipped.push({
+					page: page.label,
+					reason: summary ? `No ${CELL.formFactor}/${CELL.cacheState} median ${budget.label} in summary.json.` : "summary.json is missing."
+				});
+				continue;
+			}
+			const eligible = (run) => {
+				const value$1 = run[budget.metric];
+				return isMeasured(run) && finite(value$1) && Boolean(budget.validValue?.(value$1));
+			};
+			const representative = budget.validValue ? measuredRun(summary, index, eligible) : measuredRun(summary, index);
+			if (!representative) {
+				const requirement = budget.validValue ? `a positive LCP and valid ${budget.label}` : "a positive LCP";
+				skipped.push({
+					page: page.label,
+					reason: `Not measured: no ${CELL.formFactor}/${CELL.cacheState} run in summary.json has ${requirement}.`
+				});
+				continue;
+			}
+			const value = representative.run[budget.metric];
+			if (!finite(value)) {
+				skipped.push({
+					page: page.label,
+					reason: `No ${CELL.formFactor}/${CELL.cacheState} median ${budget.label} in summary.json.`
+				});
+				continue;
+			}
+			const runs = (summary?.runs ?? []).filter((run) => isCell(run) && (budget.validValue ? Boolean(run.row && eligible(run.row)) : !isFailedRow(run.row))).map((run) => run.row?.[budget.metric]).filter(finite);
+			measured.push({
+				page: page.label,
+				value,
+				threshold: budget.threshold,
+				runs,
+				unmeasuredRuns: representative.unmeasuredRuns
+			});
+			const left = representative.unmeasuredRuns ? `; ${representative.unmeasuredRuns} run${representative.unmeasuredRuns === 1 ? "" : "s"} not measured, left out` : "";
+			const spread = budget.includeSpread && runs.length > 1 ? `; measured spread ${budget.format(Math.min(...runs))}–${budget.format(Math.max(...runs))}` : "";
+			evidence.push({
+				type: "playhouse",
+				page: page.label,
+				artifact: "summary.json",
+				pointer: `${representative.pointer}/${budget.metric}`,
+				value: `${budget.label} ${budget.format(value)} (budget ${budget.format(budget.threshold)}${spread}${left})`
+			});
+		}
+		const data = {
+			metric: budget.metric,
+			threshold: budget.threshold,
+			cell: `${CELL.formFactor}/${CELL.cacheState}`,
+			pages: measured,
+			skipped
+		};
+		if (!measured.length) return { data };
+		const over = measured.filter((entry) => entry.value > budget.threshold);
+		const list = (entries) => entries.map((entry) => `${entry.page} ${budget.format(entry.value)}`).join(", ");
+		const severity = over.length && budget.severityForFailure ? budget.severityForFailure(Math.max(...over.map((entry) => entry.value))) : void 0;
+		const measurement = budget.measurementLabel ?? "median";
+		return {
+			data,
+			decision: over.length ? {
+				status: "fail",
+				...severity ? { severity } : {},
+				summary: `Mobile cold-cache ${measurement} ${budget.label} is over ${budget.format(budget.threshold)} on ${list(over)}.`,
+				evidence: evidence.filter((item) => over.some((entry) => entry.page === item.page))
+			} : {
+				status: "pass",
+				summary: `Mobile cold-cache ${measurement} ${budget.label} is within ${budget.format(budget.threshold)} on every measured page (${list(measured)}).`,
+				evidence
+			}
+		};
+	};
+}
+const milliseconds = (value) => `${Math.round(value)} ms`;
+
+//#endregion
+export { metricBudget as n, milliseconds as r, dataSchema as t };