pagegraph 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as contentSignal, c as renderSitemap, i as hasStructuralViolations, n as inspectHtml, o as inspectNode, r as checkGraph, s as renderRobots, t as hasBlockingIssues } from "./inspect-html-CHuoiO2s.js";
+import { i as normalizePath, n as diffLinkGraph, r as extractAnchors, t as buildRenderedGraph } from "./links-sGbLkl-7.js";
 //#region src/core/graph.ts
 /** Kind for instances whose collection route carries no declaration to inherit. */
 const FALLBACK_KIND = "page";
@@ -135,6 +135,622 @@ function buildSeoGraph(input) {
 	};
 }
 //#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;");
+/**
+* A node belongs in the sitemap when it declares a positive sitemap policy, is not
+* a redirect, is not robots-noindexed, and is not a param template (a route whose
+* path still contains a `$` segment — those exist only so their instances inherit).
+*/
+function isSitemapEligible(node) {
+	if (node.policy.redirectTo !== void 0) return false;
+	if (node.policy.robots?.includes("noindex")) return false;
+	if (!node.policy.sitemap) return false;
+	if (node.path.includes("$")) return false;
+	return true;
+}
+/** Canonical absolute URL for a node under the given origin. */
+function urlForNode(origin, node) {
+	return node.path === "/" ? origin : `${origin}${node.path}`;
+}
+/**
+* Instance lastmod: the most recent date the page's frontmatter carries. A
+* collection whose instances carry no dates (docs, a manifest-driven gallery)
+* emits no `<lastmod>` at all.
+*/
+function instanceLastmod(node) {
+	const instance = node.instance;
+	if (!instance) return void 0;
+	const date = instance.modifiedAt ?? instance.publishedAt;
+	return date ? new Date(date).toISOString() : void 0;
+}
+function renderUrlEntry(url, lastmod, node) {
+	const { changeFrequency, priority } = node.policy.sitemap;
+	const lines = [`  <url>`, `    <loc>${escapeXml(url)}</loc>`];
+	if (lastmod) lines.push(`    <lastmod>${lastmod}</lastmod>`);
+	lines.push(`    <changefreq>${changeFrequency}</changefreq>`, `    <priority>${priority.toFixed(1)}</priority>`, `  </url>`);
+	return lines.join("\n");
+}
+/**
+* Render sitemap.xml from the graph. Structural route entries emit no `<lastmod>`
+* (a route has no publish date); content instances emit it from their frontmatter.
+* Route entries are sorted by path, then instances follow in collection order.
+* `indexable` is intentionally unused — the sitemap body is host-independent;
+* robots.txt is what gates crawling.
+*/
+function renderSitemap(graph, cfg) {
+	const nodes = [...graph.nodes.values()];
+	const staticNodes = nodes.filter((node) => node.source === "route" && isSitemapEligible(node)).sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+	const instanceNodes = nodes.filter((node) => node.source !== "route" && isSitemapEligible(node));
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const node of [...staticNodes, ...instanceNodes]) {
+		const url = urlForNode(cfg.origin, node);
+		const key = url.toLowerCase().replace(/\/$/, "");
+		if (seen.has(key)) continue;
+		seen.add(key);
+		entries.push(renderUrlEntry(url, instanceLastmod(node), node));
+	}
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${entries.join("\n")}\n</urlset>\n`;
+}
+/** Format a Content-Signal robots.txt directive from the preference list. */
+function contentSignal(value) {
+	return `Content-Signal: ${value}`;
+}
+const groupLines = (cfg) => {
+	const lines = [];
+	if (cfg.contentSignal !== void 0 && cfg.contentSignal !== "") lines.push(contentSignal(cfg.contentSignal));
+	for (const directive of cfg.directives ?? []) if (directive !== "") lines.push(directive);
+	return lines;
+};
+/**
+* Render robots.txt. A non-indexable host (previews) gets a disallow-all
+* with no Sitemap line; an indexable host disallows exactly the prefixes the caller
+* passes. Pages that declare `robots: noindex` are intentionally NOT added as
+* Disallow entries — a Disallow would stop crawlers reaching the page to read its
+* `noindex, follow` meta, so the graph's per-node robots policy never feeds this
+* list. `graph` is unused — kept for signature parity with the other projections,
+* which callers load the graph once for and pass to each.
+*
+* Origin-wide group directives (`contentSignal`, `directives`) are indexable-host
+* only. {@link RobotsConfig.transform} always runs last so a consumer can override
+* the whole file.
+*/
+function renderRobots(_graph, cfg) {
+	const rendered = cfg.indexable ? [
+		"User-agent: *",
+		...groupLines(cfg),
+		"Allow: /",
+		...cfg.disallow.map((path) => `Disallow: ${path}`),
+		"",
+		`Sitemap: ${cfg.origin}/sitemap.xml`,
+		`Host: ${cfg.origin}`,
+		""
+	].join("\n") : [
+		"User-agent: *",
+		"Disallow: /",
+		""
+	].join("\n");
+	return cfg.transform === void 0 ? rendered : cfg.transform(rendered);
+}
+/** Inspect a single node: its declaration, sitemap eligibility, and edges. */
+function inspectNode(graph, path) {
+	const node = graph.nodes.get(path);
+	if (!node) return void 0;
+	return {
+		node,
+		inSitemap: isSitemapEligible(node),
+		incoming: graph.edges.filter((edge) => edge.to === path),
+		outgoing: graph.edges.filter((edge) => edge.from === path)
+	};
+}
+//#endregion
+//#region src/core/checks.ts
+/** A positive sitemap policy — the author asked for this page to be indexed. */
+const hasPositiveSitemap = (sitemap) => sitemap !== void 0 && sitemap !== false;
+/** Content and manifest instances carry page-level title/description. */
+const isInstance = (node) => node.source !== "route";
+/** Group instance nodes by a present, non-empty string field for duplicate detection. */
+const groupInstancesBy = (graph, field) => {
+	const groups = /* @__PURE__ */ new Map();
+	for (const node of graph.nodes.values()) {
+		if (!isInstance(node)) continue;
+		const value = field(node)?.trim();
+		if (!value) continue;
+		const bucket = groups.get(value);
+		if (bucket) bucket.push(node);
+		else groups.set(value, [node]);
+	}
+	return groups;
+};
+const DESCRIPTION_MAX = 160;
+const DESCRIPTION_MIN = 50;
+/**
+* Every check, in one place. `checkGraph` runs them in order and stamps each
+* finding with its rule name and severity, so the output is grouped by rule and
+* deterministic (nodes iterate in graph insertion order, edges in array order).
+*/
+const CHECK_RULES = [
+	{
+		name: "path-owner-collision",
+		severity: "structural",
+		evaluate: (graph) => (graph.collisions ?? []).map((collision) => ({
+			path: collision.path,
+			message: `Canonical path "${collision.path}" is owned by multiple sources: ${collision.sources.join(", ")}.`,
+			fix: "Give every concrete page one canonical path and one graph owner."
+		}))
+	},
+	{
+		name: "canonical-path-collision",
+		severity: "structural",
+		evaluate: (graph) => {
+			const groups = /* @__PURE__ */ new Map();
+			for (const path of graph.nodes.keys()) {
+				const canonical = path.toLowerCase().replace(/\/$/, "") || "/";
+				const paths = groups.get(canonical);
+				if (paths) paths.push(path);
+				else groups.set(canonical, [path]);
+			}
+			return [...groups.values()].filter((paths) => paths.length > 1).flatMap((paths) => paths.map((path) => ({
+				path,
+				message: `Canonical path collides with ${paths.filter((candidate) => candidate !== path).join(", ")}.`,
+				fix: "Use one lowercase, trailing-slash-normalized canonical path."
+			})));
+		}
+	},
+	{
+		name: "self-edge",
+		severity: "structural",
+		evaluate: (graph) => graph.edges.filter((edge) => edge.from === edge.to).map((edge) => ({
+			path: edge.from,
+			message: `${edge.type} edge points back to its own source node.`,
+			fix: "Remove the self-reference from the canonical manifest or route declaration."
+		}))
+	},
+	{
+		name: "duplicate-edge",
+		severity: "structural",
+		evaluate: (graph) => {
+			const seen = /* @__PURE__ */ new Set();
+			const duplicates = [];
+			for (const edge of graph.edges) {
+				const key = `${edge.from}\u0000${edge.to}\u0000${edge.type}`;
+				if (seen.has(key)) duplicates.push({
+					path: edge.from,
+					message: `Duplicate ${edge.type} edge from "${edge.from}" to "${edge.to}".`,
+					fix: "Declare each graph relationship exactly once."
+				});
+				else seen.add(key);
+			}
+			return duplicates;
+		}
+	},
+	{
+		name: "dead-edge",
+		severity: "structural",
+		evaluate: (graph) => graph.edges.filter((edge) => edge.type !== "crumb-parent" && !graph.nodes.has(edge.to)).map((edge) => ({
+			path: edge.from,
+			message: `${edge.type} edge from "${edge.from}" points at "${edge.to}", which is not a node in the graph.`,
+			fix: `Update the ${edge.type === "redirect" ? "redirectTo" : "related"} target on the "${edge.from}" route, or restore "${edge.to}".`
+		}))
+	},
+	{
+		name: "instance-missing-title",
+		severity: "structural",
+		evaluate: (graph) => [...graph.nodes.values()].filter((node) => isInstance(node) && !node.instance?.title.trim()).map((node) => ({
+			path: node.path,
+			message: `Content page "${node.path}" has no title.`,
+			fix: "Add a `title` to the page frontmatter."
+		}))
+	},
+	{
+		name: "sitemap-noindex-contradiction",
+		severity: "structural",
+		evaluate: (graph) => [...graph.nodes.values()].filter((node) => hasPositiveSitemap(node.policy.sitemap) && node.policy.robots?.toLowerCase().includes("noindex")).map((node) => ({
+			path: node.path,
+			message: `"${node.path}" declares a sitemap policy but its robots value is "${node.policy.robots}".`,
+			fix: "Drop the sitemap policy (or set `sitemap: false`) on a noindex page, or remove the noindex robots value."
+		}))
+	},
+	{
+		name: "robots-not-lowercase",
+		severity: "structural",
+		evaluate: (graph) => [...graph.nodes.values()].filter((node) => node.policy.robots !== void 0 && node.policy.robots !== node.policy.robots.toLowerCase()).map((node) => ({
+			path: node.path,
+			message: `"${node.path}" declares robots "${node.policy.robots}" — robots values must be lowercase.`,
+			fix: "Lowercase the robots declaration (e.g. \"noindex, follow\")."
+		}))
+	},
+	{
+		name: "related-target-missing-link",
+		severity: "structural",
+		evaluate: (graph) => {
+			const linklessTargets = /* @__PURE__ */ new Set();
+			for (const edge of graph.edges) {
+				if (edge.type !== "related") continue;
+				const target = graph.nodes.get(edge.to);
+				if (target && target.source === "route" && target.policy.link === void 0) linklessTargets.add(edge.to);
+			}
+			return [...linklessTargets].map((path) => ({
+				path,
+				message: `Route "${path}" is a related-link target but declares no link metadata; its card would render empty.`,
+				fix: `Add \`link: { title, description }\` to the "${path}" route's staticData.seo.`
+			}));
+		}
+	},
+	{
+		name: "redirect-in-sitemap",
+		severity: "structural",
+		evaluate: (graph) => [...graph.nodes.values()].filter((node) => node.policy.redirectTo !== void 0 && hasPositiveSitemap(node.policy.sitemap)).map((node) => ({
+			path: node.path,
+			message: `Redirect "${node.path}" (→ "${node.policy.redirectTo}") also declares a sitemap policy.`,
+			fix: "Remove the sitemap policy from the redirect route; only its target belongs in the sitemap."
+		}))
+	},
+	{
+		name: "duplicate-title",
+		severity: "editorial",
+		evaluate: (graph) => [...groupInstancesBy(graph, (node) => node.instance?.title).entries()].filter(([, nodes]) => nodes.length > 1).flatMap(([title, nodes]) => nodes.map((node) => ({
+			path: node.path,
+			message: `Title "${title}" is shared by ${nodes.length} pages.`,
+			fix: "Give each page a distinct title."
+		})))
+	},
+	{
+		name: "duplicate-description",
+		severity: "editorial",
+		evaluate: (graph) => [...groupInstancesBy(graph, (node) => node.instance?.description).entries()].filter(([, nodes]) => nodes.length > 1).flatMap(([, nodes]) => nodes.map((node) => ({
+			path: node.path,
+			message: `Description is shared by ${nodes.length} pages.`,
+			fix: "Write a distinct meta description for each page."
+		})))
+	},
+	{
+		name: "description-length",
+		severity: "editorial",
+		evaluate: (graph) => [...graph.nodes.values()].flatMap((node) => {
+			if (!isInstance(node)) return [];
+			const description = node.instance?.description?.trim();
+			if (!description) return [];
+			if (description.length > DESCRIPTION_MAX) return [{
+				path: node.path,
+				message: `Description is ${description.length} chars (max ${DESCRIPTION_MAX}); it will be truncated in results.`,
+				fix: `Trim the description to ${DESCRIPTION_MAX} characters or fewer.`
+			}];
+			if (description.length < DESCRIPTION_MIN) return [{
+				path: node.path,
+				message: `Description is ${description.length} chars (min ${DESCRIPTION_MIN}); it reads as thin.`,
+				fix: `Expand the description to at least ${DESCRIPTION_MIN} characters.`
+			}];
+			return [];
+		})
+	}
+];
+/**
+* Run every static rule against the graph, then any caller-supplied
+* {@link CoverageRule}s, and return the flat list of violations. With no
+* `coverage` option the result is exactly the static rule set.
+*/
+function checkGraph(graph, options = {}) {
+	const violations = CHECK_RULES.flatMap((rule) => rule.evaluate(graph).map((raw) => ({
+		severity: rule.severity,
+		rule: rule.name,
+		path: raw.path,
+		message: raw.message,
+		fix: raw.fix
+	})));
+	const coverage = options.coverage;
+	if (coverage !== void 0 && coverage.length > 0) violations.push(...checkCoverage(graph, coverage));
+	return violations;
+}
+/** Escape a glob for `RegExp`, then expand `**`, `*`, and `?` to path-aware forms. */
+const globToRegExp = (glob) => {
+	const source = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/\u0000/g, ".*");
+	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.
+*
+* 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 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);
+		if (eligible.length === 0) {
+			violations.push({
+				severity: "structural",
+				rule: "coverage-rule-unmatched",
+				message: matched.length === 0 ? `Coverage rule "${rule.path}" matches no page in the graph.` : `Coverage rule "${rule.path}" matches only pages that are not sitemap-eligible.`,
+				fix: "Point the rule at a sitemap-eligible path, or drop it."
+			});
+			continue;
+		}
+		for (const node of eligible) {
+			const inbound = graph.edges.filter((edge) => edge.type === "related" && edge.to === node.path).length;
+			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}".`
+			});
+		}
+	}
+	return violations;
+}
+/** Structural violations fail `pagegraph check`; editorial-only stays green. */
+const hasStructuralViolations = (violations) => violations.some((violation) => violation.severity === "structural");
+//#endregion
+//#region src/core/link-candidates.ts
+/**
+* Canonical path key: query and hash stripped, trailing slashes removed, "/"
+* preserved. This is the same path key the graph and the rendered-link core
+* use, so a served anchor like `/blog/a?ref=nav` still matches the graph pair
+* `/blog/a`.
+*/
+const normalize = (path) => {
+	const trimmed = (path.split(/[?#]/, 1)[0] ?? "").replace(/\/+$/, "");
+	return trimmed === "" ? "/" : trimmed;
+};
+/** Directionless pair key, so an edge in either direction means "connected". */
+const undirectedEdgeKey = (from, to) => {
+	const [a, b] = [normalize(from), normalize(to)].sort();
+	return `${a}\u0000${b}`;
+};
+/** First path segment, or undefined for the root page. */
+const topSegment = (path) => {
+	const segment = path.split("/").filter(Boolean)[0];
+	return segment === void 0 || segment === "" ? void 0 : segment;
+};
+/** A page with no nested segment (`/`, `/pricing`, `/blog`) is root-level. */
+const isRootLevel = (path) => path.split("/").filter(Boolean).length <= 1;
+/**
+* The cluster a pair shares, or undefined when they share none. Section-first:
+* a shared top-level section wins. The kind fallback is local to root-level
+* pages, so it never pairs two nested pages from different sections.
+*/
+const clusterOf = (a, b) => {
+	const aSegment = topSegment(a.path);
+	const bSegment = topSegment(b.path);
+	if (aSegment !== void 0 && aSegment === bSegment) return {
+		key: aSegment,
+		reason: `same top-level section "/${aSegment}"`
+	};
+	if (isRootLevel(a.path) && isRootLevel(b.path) && a.kind === b.kind) return {
+		key: `kind:${a.kind}`,
+		reason: `same kind "${a.kind}"`
+	};
+};
+/** A `--cluster` filter matches a section by name, or a kind via its bare label. */
+const matchesClusterFilter = (cluster, filter) => {
+	const normalized = filter.replace(/^\/+/, "").toLowerCase();
+	const key = cluster.toLowerCase();
+	return key === normalized || key === `kind:${normalized}`;
+};
+/** Human reason string for a candidate's source page, used when handing a plan to Jev. */
+const candidateSourceText = (node) => node.instance?.description?.trim() || node.instance?.title?.trim() || node.policy.link?.description?.trim() || node.policy.link?.title?.trim() || node.path;
+/**
+* Enumerate reviewable contextual-link candidates from the declared graph.
+*
+* Excluded: self-pairs, pages that are not sitemap-eligible, pairs already
+* declared as a `related` edge, and — when {@link LinkCandidateOptions.renderedEdges}
+* is supplied — pairs already rendered as an anchor. Queries, hashes, and
+* trailing slashes are normalized so both sides compare by the graph's path key.
+*/
+const generateLinkCandidates = (graph, options = {}) => {
+	const limit = options.limit ?? 50;
+	const filters = options.clusters ?? [];
+	const rendered = new Set((options.renderedEdges ?? []).map((edge) => undirectedEdgeKey(edge.from, edge.to)));
+	const declared = new Set(graph.edges.filter((edge) => edge.type === "related").map((edge) => undirectedEdgeKey(edge.from, edge.to)));
+	const eligible = [...graph.nodes.values()].filter(isSitemapEligible);
+	const all = [];
+	for (let i = 0; i < eligible.length; i++) for (let j = i + 1; j < eligible.length; j++) {
+		const a = eligible[i];
+		const b = eligible[j];
+		const cluster = clusterOf(a, b);
+		if (cluster === void 0) continue;
+		if (filters.length > 0 && !filters.some((filter) => matchesClusterFilter(cluster.key, filter))) continue;
+		const key = undirectedEdgeKey(a.path, b.path);
+		if (declared.has(key) || rendered.has(key)) continue;
+		all.push({
+			source: a.path,
+			destination: b.path,
+			cluster: cluster.key,
+			reason: cluster.reason
+		});
+		all.push({
+			source: b.path,
+			destination: a.path,
+			cluster: cluster.key,
+			reason: cluster.reason
+		});
+	}
+	const compare = (x, y) => x.cluster < y.cluster ? -1 : x.cluster > y.cluster ? 1 : x.source < y.source ? -1 : x.source > y.source ? 1 : x.destination < y.destination ? -1 : x.destination > y.destination ? 1 : 0;
+	all.sort(compare);
+	const counts = /* @__PURE__ */ new Map();
+	for (const pair of all) counts.set(pair.cluster, (counts.get(pair.cluster) ?? 0) + 1);
+	const candidates = all.slice(0, limit);
+	return {
+		candidates,
+		total: all.length,
+		truncated: all.length > candidates.length,
+		clusters: [...counts.entries()].map(([key, count]) => ({
+			key,
+			candidates: count
+		}))
+	};
+};
+/**
+* Decode a rendered-edge dump supplied to the CLI: either a bare array of
+* `{ from, to }` edges, or an object carrying `edges` (or `internalEdges`).
+* Throws on any other shape — this is user input, not a provider payload.
+*/
+const decodeRenderedEdges = (input) => {
+	const array = Array.isArray(input) ? input : input !== null && typeof input === "object" && Array.isArray(input.edges) ? input.edges : input !== null && typeof input === "object" && Array.isArray(input.internalEdges) ? input.internalEdges : void 0;
+	if (array === void 0) throw new Error("expected an array of { from, to } edges, or an object with an `edges` array");
+	return array.map((item) => {
+		if (item === null || typeof item !== "object") throw new Error("each rendered edge must be an object with string `from` and `to`");
+		const { from, to } = item;
+		if (typeof from !== "string" || typeof to !== "string") throw new Error("each rendered edge must have string `from` and `to`");
+		return {
+			from,
+			to
+		};
+	});
+};
+//#endregion
+//#region src/core/inspect-html.ts
+const ENTITIES = {
+	"&amp;": "&",
+	"&lt;": "<",
+	"&gt;": ">",
+	"&quot;": "\"",
+	"&#39;": "'",
+	"&apos;": "'"
+};
+const decodeEntities = (value) => value.replace(/&(?:amp|lt|gt|quot|#39|apos);/g, (match) => ENTITIES[match] ?? match);
+/** Pull double/single-quoted attributes off a single tag string. */
+const parseAttrs = (tag) => {
+	const attrs = {};
+	const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+	let match;
+	while ((match = re.exec(tag)) !== null) attrs[match[1].toLowerCase()] = decodeEntities(match[2] ?? match[3] ?? "");
+	return attrs;
+};
+/** Normalize a JSON-LD `@type` (string or array) to a single readable label. */
+const typeName = (value) => {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) return value.filter((v) => typeof v === "string").join(", ") || "unknown";
+	return "unknown";
+};
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Flatten a parsed JSON-LD payload (single object, array, or `@graph`) to items. */
+const collectItems = (parsed) => {
+	if (Array.isArray(parsed)) return parsed.filter(isObject);
+	if (isObject(parsed)) {
+		if (Array.isArray(parsed["@graph"])) return parsed["@graph"].filter(isObject);
+		return [parsed];
+	}
+	return [];
+};
+const countQuestions = (mainEntity) => {
+	if (!Array.isArray(mainEntity)) return 0;
+	return mainEntity.filter((entry) => isObject(entry) && typeName(entry["@type"]) === "Question").length;
+};
+const validateItemListElements = (value) => {
+	if (!Array.isArray(value) || value.length < 1) return ["ItemList needs at least one `itemListElement` entry."];
+	const errors = [];
+	value.forEach((entry, index) => {
+		if (!isObject(entry) || typeName(entry["@type"]) !== "ListItem") {
+			errors.push(`ItemList entry ${index + 1} is not a ListItem.`);
+			return;
+		}
+		if (entry["position"] !== index + 1) errors.push(`ItemList entry ${index + 1} has an invalid position.`);
+		if (!entry["name"] || !entry["url"]) errors.push(`ItemList entry ${index + 1} needs a name and URL.`);
+	});
+	return errors;
+};
+/** Minimal per-type validation — enough to catch an empty or malformed block. */
+const validateItem = (item) => {
+	const type = typeName(item["@type"]);
+	const errors = [];
+	if (type === "Article" || type === "NewsArticle" || type === "BlogPosting") {
+		if (!item["headline"]) errors.push("Article is missing `headline`.");
+		if (!item["datePublished"]) errors.push("Article is missing `datePublished`.");
+	} else if (type === "FAQPage") {
+		if (countQuestions(item["mainEntity"]) < 1) errors.push("FAQPage needs at least one Question in `mainEntity`.");
+	} else if (type === "BreadcrumbList") {
+		const items = item["itemListElement"];
+		if (!Array.isArray(items) || items.length < 2) errors.push("BreadcrumbList needs at least two `itemListElement` entries.");
+	} else if (type === "ItemList") {
+		errors.push(...validateItemListElements(item["itemListElement"]));
+		const items = item["itemListElement"];
+		if (Array.isArray(items) && item["numberOfItems"] !== items.length) errors.push("ItemList `numberOfItems` does not match its entries.");
+	}
+	return {
+		type,
+		valid: errors.length === 0,
+		errors
+	};
+};
+const validateLdJson = (raw) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		return [{
+			type: "unparseable",
+			valid: false,
+			errors: [`JSON parse error: ${cause instanceof Error ? cause.message : String(cause)}`]
+		}];
+	}
+	const items = collectItems(parsed);
+	if (items.length === 0) return [{
+		type: "unknown",
+		valid: false,
+		errors: ["No JSON-LD object found in block."]
+	}];
+	return items.map(validateItem);
+};
+/** Parse a rendered HTML document's `<head>` into a report. Pure. */
+const inspectHtml = (url, status, html) => {
+	const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+	const head = headMatch ? headMatch[1] : html;
+	const titleMatch = head.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+	const title = titleMatch ? decodeEntities(titleMatch[1].trim()) : void 0;
+	const og = {};
+	const twitter = {};
+	let description;
+	let robots;
+	for (const tag of head.match(/<meta\b[^>]*>/gi) ?? []) {
+		const attrs = parseAttrs(tag);
+		const content = attrs["content"];
+		if (content === void 0) continue;
+		const property = attrs["property"];
+		const name = attrs["name"];
+		if (property?.startsWith("og:")) og[property] = content;
+		else if (name?.startsWith("twitter:")) twitter[name] = content;
+		else if (name === "description") description = content;
+		else if (name === "robots") robots = content;
+	}
+	let canonical;
+	for (const tag of head.match(/<link\b[^>]*>/gi) ?? []) {
+		const attrs = parseAttrs(tag);
+		if (attrs["rel"] === "canonical") canonical = attrs["href"];
+	}
+	const jsonLd = [];
+	const scriptRe = /<script\b[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+	let scriptMatch;
+	while ((scriptMatch = scriptRe.exec(head)) !== null) jsonLd.push(...validateLdJson(scriptMatch[1].trim()));
+	const issues = [];
+	if (status >= 400) issues.push(`Fetch returned HTTP ${status}.`);
+	if (!title) issues.push("Missing <title>.");
+	if (!description) issues.push("Missing meta description.");
+	if (!canonical) issues.push("Missing canonical link.");
+	for (const block of jsonLd) if (!block.valid) issues.push(...block.errors.map((error) => `JSON-LD (${block.type}): ${error}`));
+	return {
+		url,
+		status,
+		title,
+		description,
+		canonical,
+		robots,
+		og,
+		twitter,
+		jsonLd,
+		issues
+	};
+};
+/** A non-empty `issues` list fails `pagegraph inspect --live` (exit 1). */
+const hasBlockingIssues = (report) => report.issues.length > 0;
+//#endregion
 //#region src/core/resolve-route-link.ts
 /**
 * Resolve a route's declared `seo.link` card (title + description) by its full
@@ -155,6 +771,6 @@ function resolveRouteLink(router, path) {
 	return Object.values(routesById).find((route) => route.fullPath === path)?.options.staticData?.seo?.link;
 }
 //#endregion
-export { buildSeoGraph, checkGraph, contentSignal, hasBlockingIssues, hasStructuralViolations, inspectHtml, inspectNode, renderRobots, renderSitemap, resolveRouteLink };
+export { buildRenderedGraph, buildSeoGraph, candidateSourceText, checkCoverage, checkGraph, contentSignal, decodeRenderedEdges, diffLinkGraph, extractAnchors, generateLinkCandidates, hasBlockingIssues, hasStructuralViolations, inspectHtml, inspectNode, isSitemapEligible, matchesClusterFilter, normalizePath, renderRobots, renderSitemap, resolveRouteLink, undirectedEdgeKey };
 
 //# sourceMappingURL=index.js.map