pagegraph 0.6.0 → 0.6.1

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 import * as NFS from "node:fs";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import * as NodeChildProcess from "node:child_process";
 import { spawn } from "node:child_process";
 import { PassThrough } from "node:stream";
@@ -34612,7 +34612,7 @@ const runWith = (command, config) => {
 };
 //#endregion
 //#region package.json
-var version = "0.6.0";
+var version = "0.6.1";
 //#endregion
 //#region src/core/projections.ts
 const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
@@ -34928,19 +34928,17 @@ const globToRegExp = (glob) => {
 	return new RegExp(`^${source}$`);
 };
 /**
-* Enforce contextual-link coverage rules: a named set of sitemap-eligible
-* "money" pages each needs `minInbound` incoming `related` edges. Only
-* `related` edges count — breadcrumb ancestry is navigation, not context.
+* Enforce contextual-link coverage rules over an explicit surface.
 *
 * A rule that matches no sitemap-eligible page is itself a violation: a typo or
 * a rule aimed at a noindex page would otherwise pass silently forever.
 */
-function checkCoverage(graph, rules) {
+const checkCoverageRules = (surface, rules) => {
 	const violations = [];
 	for (const rule of rules) {
 		const matcher = globToRegExp(rule.path);
-		const matched = [...graph.nodes.values()].filter((node) => matcher.test(node.path));
-		const eligible = matched.filter(isSitemapEligible);
+		const matched = surface.paths.filter((path) => matcher.test(path));
+		const eligible = surface.eligiblePaths.filter((path) => matcher.test(path));
 		if (eligible.length === 0) {
 			violations.push({
 				severity: "structural",
@@ -34950,19 +34948,55 @@ function checkCoverage(graph, rules) {
 			});
 			continue;
 		}
-		for (const node of eligible) {
-			const inbound = graph.edges.filter((edge) => edge.type === "related" && edge.to === node.path).length;
+		for (const path of eligible) {
+			const inbound = surface.inbound(path);
 			if (inbound >= rule.minInbound) continue;
 			violations.push({
 				severity: "structural",
 				rule: "inbound-link-coverage",
-				path: node.path,
-				message: `"${node.path}" has ${inbound} incoming contextual link(s); the coverage rule requires ${rule.minInbound}.`,
-				fix: `Add ${rule.minInbound - inbound} contextual (related) edge(s) pointing at "${node.path}".`
+				path,
+				message: `"${path}" has ${inbound} incoming contextual link(s); the coverage rule requires ${rule.minInbound}.`,
+				fix: `Add ${rule.minInbound - inbound} contextual link(s) pointing at "${path}".`
 			});
 		}
 	}
 	return violations;
+};
+/** The sitemap-eligible path set of a declared graph, in graph insertion order. */
+const eligiblePathsOf = (graph) => [...graph.nodes.values()].filter(isSitemapEligible).map((node) => node.path);
+/**
+* Enforce contextual-link coverage against the *declared* graph: only `related`
+* edges count — breadcrumb ancestry is navigation, not context.
+*/
+function checkCoverage(graph, rules) {
+	return checkCoverageRules({
+		paths: [...graph.nodes.keys()],
+		eligiblePaths: eligiblePathsOf(graph),
+		inbound: (path) => graph.edges.filter((edge) => edge.type === "related" && edge.to === path).length
+	}, rules);
+}
+/**
+* Enforce contextual-link coverage against the *rendered* graph: only same-origin
+* body-region anchors count. Nav, header, and footer anchors are site chrome, so
+* a page linked solely from them has no contextual inbound link — the same
+* distinction the declared pass draws by counting `related` edges alone.
+*
+* The target universe is the declared graph's sitemap-eligible pages: the globs
+* in `seo.config.ts` are written against declared paths, and the crawl is what
+* supplies the served edges. Pass the crawl's `internalEdges` (each edge carries
+* its `region`).
+*/
+function checkRenderedCoverage(graph, renderedEdges, rules) {
+	const inbound = /* @__PURE__ */ new Map();
+	for (const edge of renderedEdges) {
+		if (edge.region !== "body") continue;
+		inbound.set(edge.to, (inbound.get(edge.to) ?? 0) + 1);
+	}
+	return checkCoverageRules({
+		paths: [...graph.nodes.keys()],
+		eligiblePaths: eligiblePathsOf(graph),
+		inbound: (path) => inbound.get(path) ?? 0
+	}, rules);
 }
 /** Structural violations fail `pagegraph check`; editorial-only stays green. */
 const hasStructuralViolations = (violations) => violations.some((violation) => violation.severity === "structural");
@@ -35289,6 +35323,17 @@ const renderLinksReport = (report) => {
 		lines.push(`  rendered not declared  ${report.declared.renderedNotDeclared.length}`);
 		for (const edge of report.declared.renderedNotDeclared) lines.push(edgeLine(edge));
 	}
+	if (report.coverage !== void 0) {
+		const { coverage } = report;
+		lines.push("", `Rendered coverage (${coverage.rules} rule(s)):`);
+		if (coverage.ok) lines.push("  ✓ every coverage rule is satisfied by the served anchors.");
+		else for (const violation of coverage.violations) {
+			const where = violation.path ? `  ${violation.path}` : "";
+			lines.push(`  ✗ [${violation.rule}]${where}`);
+			lines.push(`      ${violation.message}`);
+			if (violation.fix) lines.push(`      fix: ${violation.fix}`);
+		}
+	}
 	if (crawl.failures.length > 0) {
 		lines.push("", `${crawl.failures.length} page(s) could not be fetched:`);
 		for (const failure of crawl.failures) lines.push(`  ${failure.url}  ${failure.error}`);
@@ -36214,6 +36259,30 @@ const breadthFirstDepth = (edges, root) => {
 	return depth;
 };
 /**
+* Assemble a {@link RenderedGraph} from page/edge sets. Edges are already
+* same-origin and path-keyed by the callers, so this is the shared, pure tail of
+* {@link buildRenderedGraph} and {@link renderedGraphFromEdges}.
+*/
+const graphFromEdges = (nodes, edges, root) => {
+	const rootKey = root.replace(/\/+$/, "") || "/";
+	const internalEdges = edges;
+	const contextualEdges = edges.filter((edge) => edge.region === "body");
+	const incoming = new Set(internalEdges.map((edge) => edge.to));
+	const orphans = [...nodes].filter((path) => path !== rootKey && !incoming.has(path)).sort();
+	const depthByPath = breadthFirstDepth(internalEdges, rootKey);
+	let maxDepth = null;
+	for (const value of depthByPath.values()) if (maxDepth === null || value > maxDepth) maxDepth = value;
+	return {
+		nodes: [...nodes],
+		edges,
+		internalEdges,
+		contextualEdges,
+		orphans,
+		depthByPath,
+		maxDepth
+	};
+};
+/**
 * Build the rendered graph from crawled pages. `origin` fixes the graph's
 * same-origin boundary — pages and anchors on another origin are dropped, not
 * silently folded in — and `root` is the normalized path the depth BFS starts
@@ -36222,7 +36291,6 @@ const breadthFirstDepth = (edges, root) => {
 */
 const buildRenderedGraph = (origin, pages, root = "/") => {
 	const graphOrigin = new URL(origin).origin;
-	const rootKey = root.replace(/\/+$/, "") || "/";
 	const edges = [];
 	const nodes = /* @__PURE__ */ new Set();
 	for (const page of pages) {
@@ -36252,21 +36320,39 @@ const buildRenderedGraph = (origin, pages, root = "/") => {
 			});
 		}
 	}
-	const internalEdges = edges;
-	const contextualEdges = edges.filter((edge) => edge.region === "body");
-	const incoming = new Set(internalEdges.map((edge) => edge.to));
-	const orphans = [...nodes].filter((path) => path !== rootKey && !incoming.has(path)).sort();
-	const depthByPath = breadthFirstDepth(internalEdges, rootKey);
-	let maxDepth = null;
-	for (const value of depthByPath.values()) if (maxDepth === null || value > maxDepth) maxDepth = value;
-	return {
-		edges,
-		internalEdges,
-		contextualEdges,
-		orphans,
-		depthByPath,
-		maxDepth
-	};
+	return graphFromEdges(nodes, edges, root);
+};
+/** A URL or an already-normalized graph path key both collapse to the path key. */
+const pathKeyOf = (value) => {
+	try {
+		return normalizePath(new URL(value));
+	} catch {
+		return (value.split(/[?#]/, 1)[0] ?? "").replace(/\/+$/, "") || "/";
+	}
+};
+/**
+* Rebuild a {@link RenderedGraph} from a rendered-edge set alone — the artifact
+* `pagegraph links verify --emit-rendered` writes. Path keys are normalized the
+* same way as a crawl, and `nodes` carries the rendered page paths the artifact
+* recorded, so an edge-less page (a redirect target with no internal links) stays
+* a node and its orphan/depth report survives replay. Without `nodes` the node set
+* falls back to the edge endpoints.
+*/
+const renderedGraphFromEdges = (edges, root = "/", nodes = []) => {
+	const nodeSet = new Set(nodes.map(pathKeyOf));
+	const kept = [];
+	for (const edge of edges) {
+		const from = pathKeyOf(edge.from);
+		const to = pathKeyOf(edge.to);
+		nodeSet.add(from);
+		nodeSet.add(to);
+		kept.push({
+			from,
+			to,
+			region: edge.region
+		});
+	}
+	return graphFromEdges(nodeSet, kept, root);
 };
 const edgeKey = (edge) => `${edge.from}\u0000${edge.to}`;
 const normalizeEdge = (edge) => ({
@@ -36289,6 +36375,97 @@ const diffLinkGraph = (declared, rendered) => {
 		renderedContextualCount: rendered.contextualEdges.length
 	};
 };
+const ARTIFACT_KIND = "links-rendered";
+const REGIONS = /* @__PURE__ */ new Set([
+	"nav",
+	"footer",
+	"header",
+	"body"
+]);
+const decodeArtifactEdges = (input) => {
+	if (!Array.isArray(input)) throw new Error("`edges` must be an array of { from, to, region } edges");
+	return input.map((item) => {
+		if (item === null || typeof item !== "object") throw new Error("each artifact edge must be an object with string `from` and `to`");
+		const { from, to, region } = item;
+		if (typeof from !== "string" || typeof to !== "string") throw new Error("each artifact edge must have string `from` and `to`");
+		if (region !== void 0 && !REGIONS.has(region)) throw new Error(`artifact edge region must be one of nav, footer, header, body (received ${JSON.stringify(region)})`);
+		return {
+			from,
+			to,
+			region: region ?? "body"
+		};
+	});
+};
+const decodeArtifactNodes = (input) => {
+	if (input === void 0) return [];
+	if (!Array.isArray(input) || !input.every((path) => typeof path === "string")) throw new Error("rendered-edge artifact `nodes` must be an array of paths");
+	return input;
+};
+const decodeArtifactFailures = (input) => {
+	if (input === void 0) return [];
+	if (!Array.isArray(input)) throw new Error("rendered-edge artifact `crawl.failures` must be an array");
+	return input.map((item) => {
+		if (item === null || typeof item !== "object") throw new Error("each artifact failure must be an object with string `url` and `error`");
+		const { url, error } = item;
+		if (typeof url !== "string" || typeof error !== "string") throw new Error("each artifact failure must have string `url` and `error`");
+		return {
+			url,
+			error
+		};
+	});
+};
+const requiredAbsoluteUrl = (value, field) => {
+	if (typeof value !== "string" || value === "") throw new Error(`rendered-edge artifact must carry a non-empty string \`${field}\``);
+	try {
+		new URL(value);
+	} catch {
+		throw new Error(`rendered-edge artifact \`${field}\` must be an absolute URL (received ${JSON.stringify(value)})`);
+	}
+	return value;
+};
+const requiredInteger = (value, field, minimum) => {
+	if (!Number.isSafeInteger(value) || value < minimum) throw new Error(`rendered-edge artifact \`${field}\` must be an integer >= ${minimum} (received ${JSON.stringify(value)})`);
+	return value;
+};
+/**
+* Decode a rendered-edge artifact from user input. Throws on any other shape —
+* this is user input, not a provider payload. `root`, `bodyTruncated`,
+* `truncatedPages`, `failures`, and `nodes` are optional so a hand-written edge
+* dump that only carries provenance can still be replayed.
+*/
+const decodeRenderedEdgeArtifact = (input) => {
+	if (input === null || typeof input !== "object") throw new Error("rendered-edge artifact must be an object");
+	const value = input;
+	if (value["kind"] !== ARTIFACT_KIND) throw new Error(`rendered-edge artifact \`kind\` must be "${ARTIFACT_KIND}" (received ${JSON.stringify(value["kind"])})`);
+	if (value["schemaVersion"] !== 1) throw new Error(`unsupported rendered-edge artifact schemaVersion: ${JSON.stringify(value["schemaVersion"])}`);
+	const origin = requiredAbsoluteUrl(value["origin"], "origin");
+	const seed = requiredAbsoluteUrl(value["seed"], "seed");
+	const crawl = value["crawl"];
+	if (crawl === null || typeof crawl !== "object") throw new Error("rendered-edge artifact must carry a `crawl` object");
+	const provenance = crawl;
+	const truncatedPages = provenance["truncatedPages"];
+	if (truncatedPages !== void 0 && (!Array.isArray(truncatedPages) || !truncatedPages.every((url) => typeof url === "string"))) throw new Error("rendered-edge artifact `truncatedPages` must be an array of URLs");
+	const bodyTruncated = provenance["bodyTruncated"];
+	if (bodyTruncated !== void 0 && typeof bodyTruncated !== "boolean") throw new Error("rendered-edge artifact `bodyTruncated` must be a boolean");
+	if (typeof provenance["truncated"] !== "boolean") throw new Error("rendered-edge artifact `crawl.truncated` must be a boolean");
+	return {
+		kind: ARTIFACT_KIND,
+		schemaVersion: 1,
+		origin,
+		seed,
+		crawl: {
+			pages: requiredInteger(provenance["pages"], "crawl.pages", 0),
+			root: typeof provenance["root"] === "string" ? provenance["root"] : pathKeyOf(seed),
+			limit: requiredInteger(provenance["limit"], "crawl.limit", 1),
+			truncated: provenance["truncated"],
+			bodyTruncated: bodyTruncated === true,
+			truncatedPages: truncatedPages ?? [],
+			failures: decodeArtifactFailures(provenance["failures"])
+		},
+		nodes: decodeArtifactNodes(value["nodes"]),
+		edges: decodeArtifactEdges(value["edges"])
+	};
+};
 //#endregion
 //#region src/audit/network.ts
 const blockedIpv4Addresses = new BlockList();
@@ -41531,110 +41708,234 @@ const decodeLinkCandidates = (input) => decodeUnknownSync(ArraySchema(LinkCandid
 //#region src/cli/commands/links.ts
 const messageOf = (cause) => cause instanceof Error ? cause.message : String(cause);
 const positive = (name, value) => Number.isSafeInteger(value) && value > 0 ? succeed$2(value) : fail$3(new SeoCliError({ message: `--${name} must be a positive integer` }));
-const urlArg = String$1("url").pipe(withDescription("Absolute http(s) URL of the site homepage to crawl"));
+const urlArg = String$1("url").pipe(withDescription("Absolute http(s) URL of the site homepage to crawl (omit with --rendered)"), optional);
 const limitFlag = Int("limit").pipe(withDescription$2("Maximum pages to fetch, including the homepage"), withDefault(100));
 const allowPrivate = Boolean$1("allow-private").pipe(withDescription$2("Allow localhost and private addresses (local development only)"), withDefault(false));
 const requestTimeoutMs = Int("request-timeout-ms").pipe(withDescription$2("HTTP request timeout in milliseconds"), withDefault(15e3));
 const maxBodyBytes = Int("max-body-bytes").pipe(withDescription$2("Maximum captured response bytes per page"), withDefault(2e6));
 /**
-* The declared graph is optional input. A missing `seo.config.ts` means the
-* rendered-only report; a config that exists but fails to load is a warning, not
-* a failure, because verifying served HTML works on any deployed site. Origins
-* are compared before diffing, so a graph from another project is never silently
-* attributed to this crawl.
+* Load the app's declared graph when a `seo.config.ts` exists and derive the two
+* things `verify` needs from it: the declared `related` edges for the diff, and —
+* under `--assert-coverage` — the rendered coverage assertion. Both are computed
+* inside one scoped graph acquisition so the Vite loader is acquired once.
+*
+* Without `--assert-coverage` the declared graph is optional enrichment: a
+* missing or broken config, an invalid origin, or an origin mismatch each become a
+* warning, because verifying served HTML works on any deployed site. Under
+* `--assert-coverage` every one of those is a hard failure — an assertion must
+* know which pages the rules target and that this crawl is the same site, and a
+* truncated crawl is refused before the graph is even loaded.
 */
-const loadDeclaredGraph = gen(function* () {
-	const config = yield* loadSeoConfigOptional;
-	if (config === void 0) return { kind: "absent" };
+const analyzeDeclared = (crawlOrigin, renderedEdges, assertCoverage, crawlState) => gen(function* () {
+	if (assertCoverage) {
+		if (crawlState.truncated) return yield* new SeoCliError({ message: "Refusing to assert rendered coverage on a truncated crawl; re-run with a higher --limit." });
+		if (crawlState.failures > 0) return yield* new SeoCliError({ message: `Refusing to assert rendered coverage: ${crawlState.failures} page(s) failed to fetch, so their anchors are missing.` });
+		if (crawlState.bodyTruncated) return yield* new SeoCliError({ message: "Refusing to assert rendered coverage when a crawled body was truncated; raise --max-body-bytes." });
+	}
+	const warnings = [];
+	const config = yield* loadSeoConfigOptional.pipe(catchTag("SeoCliError", (error) => assertCoverage ? fail$3(error) : sync(() => {
+		warnings.push(`Ignoring declared graph: ${error.message}`);
+	})));
+	if (config === void 0) {
+		if (assertCoverage) return yield* new SeoCliError({ message: "Coverage assertion needs a seo.config.ts declaring `coverage` rules." });
+		return {
+			declaredEdges: void 0,
+			coverage: void 0,
+			warnings
+		};
+	}
 	let configOrigin;
 	try {
 		configOrigin = new URL(config.origin).origin;
 	} catch {
+		const message = `Ignoring declared graph: seo.config.ts origin "${config.origin}" is not a valid URL.`;
+		if (assertCoverage) return yield* new SeoCliError({ message });
+		warnings.push(message);
 		return {
-			kind: "warning",
-			message: `Ignoring declared graph: seo.config.ts origin "${config.origin}" is not a valid URL.`
+			declaredEdges: void 0,
+			coverage: void 0,
+			warnings
 		};
 	}
-	const graph = yield* scoped(acquireGraph(config));
-	return {
-		kind: "loaded",
-		graph: {
-			origin: configOrigin,
-			edges: graph.edges.filter((edge) => edge.type === "related").map((edge) => ({
+	const rules = config.coverage ?? [];
+	if (assertCoverage && rules.length === 0) return yield* new SeoCliError({ message: "seo.config.ts declares no `coverage` rules; nothing to assert." });
+	if (configOrigin !== crawlOrigin) {
+		const mismatch = `declared graph origin ${configOrigin} differs from crawled origin ${crawlOrigin}`;
+		if (assertCoverage) return yield* new SeoCliError({ message: `Cannot assert coverage: ${mismatch}.` });
+		warnings.push(`${mismatch.charAt(0).toUpperCase()}${mismatch.slice(1)}; skipping the declared-vs-rendered diff.`);
+		return {
+			declaredEdges: void 0,
+			coverage: void 0,
+			warnings
+		};
+	}
+	return yield* scoped(gen(function* () {
+		const graph = yield* acquireGraph(config);
+		return {
+			declaredEdges: graph.edges.filter((edge) => edge.type === "related").map((edge) => ({
 				from: edge.from,
 				to: edge.to
-			}))
-		}
-	};
-}).pipe(catchTag("SeoCliError", (error) => succeed$2({
-	kind: "warning",
-	message: `Ignoring declared graph: ${error.message}`
-})));
+			})),
+			coverage: assertCoverage ? {
+				rules: rules.length,
+				violations: checkRenderedCoverage(graph, renderedEdges, rules)
+			} : void 0,
+			warnings
+		};
+	}));
+});
+/** Read and decode a saved rendered-edge artifact; the file is user input. */
+const readRenderedArtifact = (file) => try_({
+	try: () => decodeRenderedEdgeArtifact(JSON.parse(readFileSync(file, "utf8"))),
+	catch: (cause) => new SeoCliError({ message: `Could not read rendered artifact from ${file}: ${messageOf(cause)}` })
+});
+/** Write a rendered-edge artifact, creating its parent directory when needed. */
+const writeRenderedArtifact = (file, artifact) => try_({
+	try: () => {
+		mkdirSync(dirname(resolve(file)), { recursive: true });
+		writeFileSync(file, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+	},
+	catch: (cause) => new SeoCliError({ message: `Could not write rendered artifact to ${file}: ${messageOf(cause)}` })
+});
 const linksVerifyCommand = make$9("verify", {
 	url: urlArg,
 	json: jsonFlag,
 	limit: limitFlag,
 	allowPrivate,
 	requestTimeoutMs,
-	maxBodyBytes
+	maxBodyBytes,
+	emitRendered: String$2("emit-rendered").pipe(withDescription$2("Write the crawled rendered-edge artifact to this path (crawl mode)"), optional$1),
+	rendered: String$2("rendered").pipe(withDescription$2("Replay a saved rendered-edge artifact instead of crawling"), optional$1),
+	assertCoverage: Boolean$1("assert-coverage").pipe(withDescription$2("Assert seo.config.ts coverage rules against the rendered anchors; exit 1 on unmet (refuses truncated crawls)"), withDefault(false))
 }).pipe(withDescription$1("Crawl served HTML and report homepage depth, rendered orphans, and the declared-vs-rendered gap"), withExamples([
 	{
 		command: "pagegraph links verify https://example.com",
 		description: "Crawl the homepage and report the rendered link graph"
 	},
 	{
-		command: "pagegraph links verify https://example.com --limit 25",
-		description: "Bound the crawl to 25 pages"
+		command: "pagegraph links verify https://example.com --limit 25 --json | jq",
+		description: "Bound the crawl to 25 pages and emit versioned JSON"
 	},
 	{
-		command: "pagegraph links verify https://example.com --json | jq",
-		description: "One versioned JSON report on stdout"
+		command: "pagegraph links verify https://example.com --emit-rendered rendered.json",
+		description: "Crawl once and save the rendered-edge artifact"
+	},
+	{
+		command: "pagegraph links verify --rendered rendered.json --assert-coverage",
+		description: "Assert seo.config.ts coverage offline against a saved crawl (exit 1 on unmet)"
+	},
+	{
+		command: "pagegraph links verify https://example.com --assert-coverage",
+		description: "Crawl and assert coverage against the served anchors in one pass"
 	},
 	{
 		command: "pagegraph links verify http://localhost:3000 --allow-private",
 		description: "Verify a local app"
 	}
 ]), withHandler(fn("SeoCli.linksVerify")(function* (options) {
-	const checkedLimit = yield* positive("limit", options.limit);
-	const checkedTimeout = yield* positive("request-timeout-ms", options.requestTimeoutMs);
-	const checkedMaxBody = yield* positive("max-body-bytes", options.maxBodyBytes);
-	const crawl = yield* tryPromise({
-		try: () => crawlRenderedPages(options.url, {
-			limit: checkedLimit,
-			timeoutMs: checkedTimeout,
-			maxBodyBytes: checkedMaxBody,
-			allowPrivate: options.allowPrivate
-		}),
-		catch: (cause) => new SeoCliError({ message: `Could not crawl ${options.url}: ${messageOf(cause)}` })
-	});
-	if (crawl.pages.length === 0) {
-		const reason = crawl.failures[0]?.error ?? "no pages fetched";
-		return yield* new SeoCliError({ message: `No page could be crawled at ${options.url}: ${reason}` });
-	}
-	const graph = buildRenderedGraph(crawl.origin, crawl.pages, crawl.root);
+	const emitPath = getOrUndefined$1(options.emitRendered);
+	const artifactPath = getOrUndefined$1(options.rendered);
+	const url = getOrUndefined$1(options.url);
+	if (emitPath !== void 0 && artifactPath !== void 0) return yield* new SeoCliError({ message: "--emit-rendered writes a fresh crawl; --rendered replays one. Use one or the other." });
+	if (url === void 0 && artifactPath === void 0) return yield* new SeoCliError({ message: "Provide a homepage URL to crawl, or --rendered <path> to replay a saved crawl." });
 	const warnings = [];
-	if (crawl.truncatedBodies.length > 0) warnings.push(`${crawl.truncatedBodies.length} page body/bodies exceeded --max-body-bytes; anchors past the cutoff are missing.`);
-	const declared = yield* loadDeclaredGraph;
-	let declaredEdges;
-	if (declared.kind === "warning") warnings.push(declared.message);
-	if (declared.kind === "loaded") if (declared.graph.origin === crawl.origin) declaredEdges = declared.graph.edges;
-	else warnings.push(`Declared graph origin ${declared.graph.origin} differs from crawled origin ${crawl.origin}; skipping the declared-vs-rendered diff.`);
-	const diff = declaredEdges === void 0 ? void 0 : diffLinkGraph(declaredEdges, graph);
-	const report = {
-		kind: "links-verify",
-		schemaVersion: 1,
-		origin: crawl.origin,
-		seed: crawl.seed,
-		crawl: {
+	let origin;
+	let seed;
+	let graph;
+	let renderedEdges;
+	let crawlReport;
+	if (artifactPath !== void 0) {
+		const artifact = yield* readRenderedArtifact(artifactPath);
+		if (url !== void 0) {
+			let requestedOrigin;
+			try {
+				requestedOrigin = new URL(url).origin;
+			} catch {
+				return yield* new SeoCliError({ message: `Not a valid URL: ${url}` });
+			}
+			if (requestedOrigin !== new URL(artifact.origin).origin) return yield* new SeoCliError({ message: `--rendered artifact origin ${artifact.origin} does not match ${url}.` });
+		}
+		origin = artifact.origin;
+		seed = artifact.seed;
+		graph = renderedGraphFromEdges(artifact.edges, artifact.crawl.root, artifact.nodes);
+		renderedEdges = artifact.edges;
+		crawlReport = {
+			pages: artifact.crawl.pages,
+			limit: artifact.crawl.limit,
+			truncated: artifact.crawl.truncated,
+			failures: artifact.crawl.failures,
+			bodyTruncated: artifact.crawl.bodyTruncated,
+			truncatedPages: artifact.crawl.truncatedPages
+		};
+	} else {
+		const checkedLimit = yield* positive("limit", options.limit);
+		const checkedTimeout = yield* positive("request-timeout-ms", options.requestTimeoutMs);
+		const checkedMaxBody = yield* positive("max-body-bytes", options.maxBodyBytes);
+		const crawl = yield* tryPromise({
+			try: () => crawlRenderedPages(url, {
+				limit: checkedLimit,
+				timeoutMs: checkedTimeout,
+				maxBodyBytes: checkedMaxBody,
+				allowPrivate: options.allowPrivate
+			}),
+			catch: (cause) => new SeoCliError({ message: `Could not crawl ${url}: ${messageOf(cause)}` })
+		});
+		if (crawl.pages.length === 0) return yield* new SeoCliError({ message: `No page could be crawled at ${url}: ${crawl.failures[0]?.error ?? "no pages fetched"}` });
+		graph = buildRenderedGraph(crawl.origin, crawl.pages, crawl.root);
+		renderedEdges = graph.internalEdges;
+		origin = crawl.origin;
+		seed = crawl.seed;
+		crawlReport = {
 			pages: crawl.pages.length,
 			limit: crawl.limit,
 			truncated: crawl.truncated,
 			failures: crawl.failures,
 			bodyTruncated: crawl.truncatedBodies.length > 0,
 			truncatedPages: crawl.truncatedBodies
-		},
+		};
+		if (emitPath !== void 0) {
+			const artifact = {
+				kind: "links-rendered",
+				schemaVersion: 1,
+				origin: crawl.origin,
+				seed: crawl.seed,
+				crawl: {
+					pages: crawl.pages.length,
+					root: crawl.root,
+					limit: crawl.limit,
+					truncated: crawl.truncated,
+					bodyTruncated: crawl.truncatedBodies.length > 0,
+					truncatedPages: crawl.truncatedBodies,
+					failures: crawl.failures
+				},
+				nodes: graph.nodes,
+				edges: graph.internalEdges
+			};
+			yield* writeRenderedArtifact(emitPath, artifact);
+			yield* logInfo(`Wrote rendered edges to ${emitPath}`);
+		}
+	}
+	if (crawlReport.truncatedPages.length > 0) warnings.push(`${crawlReport.truncatedPages.length} page body/bodies exceeded --max-body-bytes; anchors past the cutoff are missing.`);
+	const analysis = yield* analyzeDeclared(origin, renderedEdges, options.assertCoverage, {
+		truncated: crawlReport.truncated,
+		bodyTruncated: crawlReport.bodyTruncated,
+		failures: crawlReport.failures.length
+	});
+	warnings.push(...analysis.warnings);
+	const diff = analysis.declaredEdges === void 0 ? void 0 : diffLinkGraph(analysis.declaredEdges, graph);
+	const coverage = analysis.coverage === void 0 ? void 0 : {
+		rules: analysis.coverage.rules,
+		ok: analysis.coverage.violations.length === 0,
+		violations: analysis.coverage.violations
+	};
+	const report = {
+		kind: "links-verify",
+		schemaVersion: 1,
+		origin,
+		seed,
+		crawl: crawlReport,
 		rendered: {
-			pages: crawl.pages.length,
+			pages: crawlReport.pages,
 			internalEdges: graph.internalEdges.length,
 			contextualEdges: graph.contextualEdges.length,
 			maxDepth: graph.maxDepth,
@@ -41646,10 +41947,12 @@ const linksVerifyCommand = make$9("verify", {
 			declaredNotRendered: diff.declaredNotRendered,
 			renderedNotDeclared: diff.renderedNotDeclared
 		},
+		...coverage === void 0 ? {} : { coverage },
 		warnings
 	};
 	if (options.json) yield* printJson(report);
 	else yield* printText(renderLinksReport(report));
+	if (coverage !== void 0 && !coverage.ok) return yield* new SeoCliError({ message: `${coverage.violations.length} rendered coverage violation(s) — the served anchors do not satisfy seo.config.ts.` });
 })));
 const decideFile = String$1("file").pipe(withDescription("JSON file with an array of link candidates (default: stdin)"), optional);
 const thresholdFlag = Finite("threshold").pipe(withDescription$2("Probability above which an answer is confident; below is review (0.5 < t < 1)"), withDefault(DEFAULT_LINK_THRESHOLD));