pagetrace 0.2.0

package/dist/cli.cjs

@@ -0,0 +1,1541 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_promises2 = require("fs/promises");
+var import_cac = require("cac");
+var import_picocolors2 = __toESM(require("picocolors"), 1);
+
+// src/rules/rich-results.ts
+var RICH_RESULT_RULES = {
+  Article: {
+    required: ["headline"],
+    recommended: ["author", "datePublished", "dateModified", "image"]
+  },
+  NewsArticle: {
+    required: ["headline"],
+    recommended: ["author", "datePublished", "dateModified", "image"]
+  },
+  BlogPosting: {
+    required: ["headline"],
+    recommended: ["author", "datePublished", "dateModified", "image"]
+  },
+  Product: {
+    required: ["name"],
+    recommended: ["image", "description", "brand"],
+    oneOf: [["offers", "review", "aggregateRating"]]
+  },
+  Offer: {
+    required: ["price", "priceCurrency"],
+    recommended: ["availability", "url"]
+  },
+  FAQPage: {
+    required: ["mainEntity"],
+    recommended: []
+  },
+  HowTo: {
+    required: ["name", "step"],
+    recommended: ["image", "totalTime", "supply", "tool"]
+  },
+  Recipe: {
+    required: ["name", "image"],
+    recommended: ["author", "datePublished", "description", "recipeIngredient", "recipeInstructions"]
+  },
+  Event: {
+    required: ["name", "startDate", "location"],
+    recommended: ["endDate", "description", "image", "offers"]
+  },
+  JobPosting: {
+    required: ["title", "description", "datePosted", "hiringOrganization"],
+    recommended: ["jobLocation", "baseSalary", "validThrough", "employmentType"]
+  },
+  Organization: {
+    required: ["name"],
+    recommended: ["url", "logo", "sameAs", "contactPoint"]
+  },
+  LocalBusiness: {
+    required: ["name", "address"],
+    recommended: ["telephone", "openingHoursSpecification", "geo", "priceRange", "image"]
+  },
+  BreadcrumbList: {
+    required: ["itemListElement"],
+    recommended: []
+  },
+  VideoObject: {
+    required: ["name", "description", "thumbnailUrl", "uploadDate"],
+    recommended: ["duration", "contentUrl", "embedUrl"]
+  },
+  Review: {
+    required: ["itemReviewed", "reviewRating", "author"],
+    recommended: ["datePublished", "reviewBody"]
+  },
+  AggregateRating: {
+    required: ["ratingValue"],
+    recommended: ["reviewCount", "ratingCount", "bestRating"]
+  },
+  Course: {
+    required: ["name", "description"],
+    recommended: ["provider", "offers", "hasCourseInstance"]
+  },
+  SoftwareApplication: {
+    required: ["name", "applicationCategory"],
+    recommended: ["operatingSystem", "offers", "aggregateRating"]
+  },
+  WebSite: {
+    required: ["name", "url"],
+    recommended: ["potentialAction"]
+  },
+  Person: {
+    required: ["name"],
+    recommended: ["url", "jobTitle", "sameAs", "image"]
+  }
+};
+var DEFAULT_AI_AGENTS = [
+  "GPTBot",
+  "OAI-SearchBot",
+  "ChatGPT-User",
+  "ClaudeBot",
+  "Claude-User",
+  "PerplexityBot",
+  "Perplexity-User",
+  "Google-Extended",
+  "Applebot-Extended",
+  "CCBot",
+  "Bytespider",
+  "meta-externalagent"
+];
+
+// src/audit.ts
+function auditPage(page, config = {}) {
+  const findings = [];
+  const at = (code, severity, message, extra = {}) => findings.push({ code, severity, route: page.route, message, ...extra });
+  if (!page.title) at("title.missing", "error", "Page has no <title>.");
+  else if (page.title.length > 65)
+    at("title.long", "info", "Title is long enough that it will likely be truncated in results.", {
+      after: page.title.length
+    });
+  if (!page.description) at("description.missing", "warn", "Page has no meta description.");
+  if (!page.canonical) at("canonical.missing", "error", "Page has no canonical URL.");
+  if (page.robots?.includes("noindex")) at("robots.noindex", "warn", "Page is marked noindex.");
+  if (page.h1.length === 0) at("h1.missing", "error", "Page has no <h1>.");
+  else if (page.h1.length > 1)
+    at("h1.multiple", "warn", "Page has more than one <h1>.", { after: page.h1 });
+  if (!page.og["og:title"]) at("og.title.missing", "warn", "Missing og:title.");
+  if (!page.og["og:image"]) at("og.image.missing", "warn", "Missing og:image.");
+  if (page.jsonLd.length === 0)
+    at("jsonld.missing", "warn", "Page has no JSON-LD structured data.");
+  for (const entity of page.jsonLd) {
+    if (entity.type === "__parse_error__") {
+      at("jsonld.invalid", "error", "A JSON-LD block failed to parse.");
+      continue;
+    }
+    const rule = RICH_RESULT_RULES[entity.type];
+    if (!rule) continue;
+    const present = new Set(entity.properties);
+    const missing = rule.required.filter((p) => !present.has(p));
+    if (missing.length > 0) {
+      at(
+        "jsonld.required.missing",
+        "error",
+        `${entity.type} is missing required ${missing.length === 1 ? "property" : "properties"}: ${missing.join(", ")}.`,
+        { after: entity.properties }
+      );
+    }
+    for (const group of rule.oneOf ?? []) {
+      if (!group.some((p) => present.has(p))) {
+        at(
+          "jsonld.oneof.missing",
+          "error",
+          `${entity.type} needs at least one of: ${group.join(", ")}.`
+        );
+      }
+    }
+    const missingRecommended = rule.recommended.filter((p) => !present.has(p));
+    if (missingRecommended.length > 0) {
+      at(
+        "jsonld.recommended.missing",
+        "info",
+        `${entity.type} is missing recommended: ${missingRecommended.join(", ")}.`
+      );
+    }
+  }
+  const minWords = config.minWordCount ?? 150;
+  if (page.wordCount < minWords)
+    at("content.thin", "warn", `Page has fewer than ${minWords} words.`, {
+      after: page.wordCount
+    });
+  if (page.leadAnswerWords === 0)
+    at("aeo.lead.missing", "warn", "No substantive opening paragraph for an answer engine to quote.");
+  else if (page.leadAnswerWords > 120)
+    at("aeo.lead.long", "info", "Opening paragraph is long; under ~80 words extracts better.", {
+      after: page.leadAnswerWords
+    });
+  if (page.images.missingAlt > 0)
+    at("images.alt.missing", "warn", "Page has images with no alt attribute.", {
+      after: { missingAlt: page.images.missingAlt, total: page.images.total }
+    });
+  return findings;
+}
+function auditSite(snapshot) {
+  const findings = [];
+  const { site } = snapshot;
+  if (!site.robotsTxt?.present) {
+    findings.push({ code: "robotstxt.missing", severity: "warn", route: null, message: "No robots.txt found." });
+  } else {
+    const blocked = Object.entries(site.robotsTxt.aiAgents).filter(([, state]) => state === "disallowed").map(([agent]) => agent);
+    if (blocked.length > 0) {
+      findings.push({
+        code: "aeo.crawler.blocked",
+        severity: "info",
+        route: null,
+        message: `robots.txt blocks ${blocked.length} AI crawler(s): ${blocked.join(", ")}.`,
+        after: blocked
+      });
+    }
+    if (site.robotsTxt.sitemaps.length === 0) {
+      findings.push({
+        code: "robotstxt.sitemap.missing",
+        severity: "warn",
+        route: null,
+        message: "robots.txt does not declare a sitemap."
+      });
+    }
+  }
+  if (!site.llmsTxt?.present) {
+    findings.push({
+      code: "aeo.llmstxt.missing",
+      severity: "info",
+      route: null,
+      message: "No /llms.txt found."
+    });
+  }
+  return findings;
+}
+function originOf(href) {
+  try {
+    return new URL(href).origin;
+  } catch {
+    return null;
+  }
+}
+var VARIANT_SUFFIX = /(?:\/(?:page|p)\/\d+|\/amp)\/?$/i;
+var AMP_PREFIX = /^\/amp(?=\/)/i;
+function isVariantOf(route, target) {
+  return [route.replace(VARIANT_SUFFIX, ""), route.replace(AMP_PREFIX, "")].filter((stripped) => stripped !== route).some((stripped) => (stripped === "" ? "/" : stripped) === target);
+}
+function pathOf(href) {
+  try {
+    const path = new URL(href, "https://placeholder.invalid").pathname.replace(/\/+$/, "");
+    return path === "" ? "/" : path;
+  } catch {
+    return null;
+  }
+}
+function auditCrossPage(snapshot) {
+  const findings = [];
+  const pages = Object.values(snapshot.pages);
+  const group = (key) => {
+    const map = /* @__PURE__ */ new Map();
+    for (const page of pages) {
+      const value = key(page);
+      if (value === null || value === void 0 || value === "") continue;
+      if (!map.has(value)) map.set(value, []);
+      map.get(value).push(page.route);
+    }
+    return map;
+  };
+  for (const [title, routes] of group((p) => p.title)) {
+    if (routes.length > 1) {
+      findings.push({
+        code: "duplicate.title",
+        severity: "warn",
+        route: null,
+        message: `${routes.length} pages share the title "${title}".`,
+        after: routes
+      });
+    }
+  }
+  for (const [, routes] of group((p) => p.description)) {
+    if (routes.length > 1) {
+      findings.push({
+        code: "duplicate.description",
+        severity: "warn",
+        route: null,
+        message: `${routes.length} pages share the same meta description.`,
+        after: routes
+      });
+    }
+  }
+  for (const [canonical, routes] of group((p) => p.canonical)) {
+    if (routes.length > 1) {
+      findings.push({
+        code: "duplicate.canonical",
+        severity: "error",
+        route: null,
+        message: `${routes.length} pages canonicalise to ${canonical}.`,
+        after: routes
+      });
+    }
+  }
+  const expectedOrigin = snapshot.site.origin ?? null;
+  for (const page of pages) {
+    if (!page.canonical) continue;
+    if (expectedOrigin !== null) {
+      const host = originOf(page.canonical);
+      if (host !== null && host !== expectedOrigin) {
+        findings.push({
+          code: "canonical.offsite",
+          severity: "error",
+          route: page.route,
+          message: "Canonical points at another host.",
+          before: expectedOrigin,
+          after: page.canonical
+        });
+        continue;
+      }
+    }
+    const normalized = pathOf(page.canonical);
+    if (normalized === null || normalized === page.route) continue;
+    if (isVariantOf(page.route, normalized)) continue;
+    findings.push({
+      code: "canonical.crosspath",
+      severity: "warn",
+      route: page.route,
+      message: "Canonical points to a different path.",
+      before: page.route,
+      after: page.canonical
+    });
+  }
+  return findings;
+}
+var LANG_TAG = /^[a-z]{2,3}(-[a-zA-Z0-9]{2,8})*$/i;
+function auditHreflang(snapshot) {
+  const findings = [];
+  const pages = Object.values(snapshot.pages);
+  const annotated = pages.filter((p) => Object.keys(p.hreflang).length > 0);
+  if (annotated.length === 0) return findings;
+  const byRoute = new Map(pages.map((p) => [p.route, p]));
+  const claimed = /* @__PURE__ */ new Set();
+  for (const page of annotated) {
+    for (const href of Object.values(page.hreflang)) {
+      const target = pathOf(href);
+      if (target !== null && target !== page.route) claimed.add(target);
+    }
+  }
+  for (const page of pages) {
+    const entries = Object.entries(page.hreflang);
+    if (entries.length === 0) {
+      if (claimed.has(page.route)) {
+        findings.push({
+          code: "hreflang.missing",
+          severity: "warn",
+          route: page.route,
+          message: "Page is named as an hreflang alternate but declares none of its own."
+        });
+      }
+      continue;
+    }
+    const invalid = entries.map(([lang]) => lang).filter((lang) => lang !== "x-default" && !LANG_TAG.test(lang));
+    if (invalid.length > 0) {
+      findings.push({
+        code: "hreflang.invalid",
+        severity: "warn",
+        route: page.route,
+        message: "Page has malformed hreflang language codes.",
+        after: invalid
+      });
+    }
+    const targets = [
+      ...new Set(
+        entries.map(([, href]) => pathOf(href)).filter((p) => p !== null)
+      )
+    ];
+    if (!targets.includes(page.route)) {
+      findings.push({
+        code: "hreflang.self.missing",
+        severity: "warn",
+        route: page.route,
+        message: "Page does not include a self-referencing hreflang."
+      });
+    }
+    if (!entries.some(([lang]) => lang === "x-default")) {
+      findings.push({
+        code: "hreflang.xdefault.missing",
+        severity: "info",
+        route: page.route,
+        message: "Page has hreflang alternates but no x-default."
+      });
+    }
+    const broken = [];
+    for (const target of targets) {
+      if (target === page.route) continue;
+      const other = byRoute.get(target);
+      if (!other) continue;
+      const returns = Object.values(other.hreflang).map(pathOf).includes(page.route);
+      if (!returns) broken.push(target);
+    }
+    if (broken.length > 0) {
+      findings.push({
+        code: "hreflang.nonreciprocal",
+        severity: "error",
+        route: page.route,
+        message: "Page points at alternates that do not point back.",
+        after: broken
+      });
+    }
+    for (const target of targets) {
+      if (target === page.route) continue;
+      const other = byRoute.get(target);
+      if (other?.robots?.includes("noindex")) {
+        findings.push({
+          code: "hreflang.noindex.target",
+          severity: "error",
+          route: page.route,
+          message: "Page declares an hreflang alternate that is noindexed.",
+          after: target
+        });
+      }
+    }
+  }
+  return findings;
+}
+function auditSnapshot(snapshot, config = {}) {
+  return [
+    ...auditSite(snapshot),
+    ...auditCrossPage(snapshot),
+    ...auditHreflang(snapshot),
+    ...Object.values(snapshot.pages).flatMap((page) => auditPage(page, config))
+  ];
+}
+
+// src/diff.ts
+function transition(before, after) {
+  if (before === after) return "unchanged";
+  if (before === null) return "added";
+  if (after === null) return "removed";
+  return "changed";
+}
+var SCALAR_FIELDS = [
+  { field: "title", label: "Title", code: "title", onRemoved: "error", onChanged: "info", onAdded: "info" },
+  { field: "description", label: "Meta description", code: "description", onRemoved: "warn", onChanged: "info", onAdded: "info" },
+  { field: "canonical", label: "Canonical", code: "canonical", onRemoved: "error", onChanged: "warn", onAdded: "info" }
+];
+function indexEntities(entities) {
+  const map = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Map();
+  for (const entity of entities) {
+    if (entity.id !== void 0 && !map.has(entity.id)) {
+      map.set(entity.id, entity);
+      continue;
+    }
+    const nth = (seen.get(entity.type) ?? 0) + 1;
+    seen.set(entity.type, nth);
+    map.set(`${entity.type}#${nth}`, entity);
+  }
+  return map;
+}
+function diffPage(before, after) {
+  const findings = [];
+  const route = after.route;
+  const push = (code, severity, message, extra = {}) => findings.push({ code, severity, route, message, ...extra });
+  for (const rule of SCALAR_FIELDS) {
+    const b = before[rule.field];
+    const a = after[rule.field];
+    switch (transition(b, a)) {
+      case "removed":
+        push(`${rule.code}.removed`, rule.onRemoved, `${rule.label} was removed.`, { before: b });
+        break;
+      case "added":
+        push(`${rule.code}.added`, rule.onAdded, `${rule.label} was added.`, { after: a });
+        break;
+      case "changed":
+        push(`${rule.code}.changed`, rule.onChanged, `${rule.label} changed.`, { before: b, after: a });
+        break;
+    }
+  }
+  const wasNoindex = before.robots?.includes("noindex") ?? false;
+  const isNoindex = after.robots?.includes("noindex") ?? false;
+  if (!wasNoindex && isNoindex)
+    push("robots.noindex.added", "error", "Page became noindex.", { before: before.robots, after: after.robots });
+  if (wasNoindex && !isNoindex)
+    push("robots.noindex.removed", "info", "Page is no longer noindex.", { before: before.robots });
+  const wasNofollow = before.robots?.includes("nofollow") ?? false;
+  const isNofollow = after.robots?.includes("nofollow") ?? false;
+  if (!wasNofollow && isNofollow)
+    push("robots.nofollow.added", "warn", "Page became nofollow.", { after: after.robots });
+  const beforeEntities = indexEntities(before.jsonLd);
+  const afterEntities = indexEntities(after.jsonLd);
+  for (const [key, entity] of beforeEntities) {
+    if (!afterEntities.has(key)) {
+      push("jsonld.entity.removed", "error", `Structured data entity ${entity.type} was removed.`, {
+        before: entity
+      });
+    }
+  }
+  for (const [key, entity] of afterEntities) {
+    if (!beforeEntities.has(key)) {
+      push("jsonld.entity.added", "info", `Structured data entity ${entity.type} was added.`, { after: entity });
+      continue;
+    }
+    const prev = beforeEntities.get(key);
+    const dropped = prev.properties.filter((p) => !entity.properties.includes(p));
+    if (dropped.length > 0) {
+      push("jsonld.property.removed", "error", `${entity.type} lost structured data properties.`, {
+        before: prev.properties,
+        after: entity.properties
+      });
+    }
+  }
+  for (const [group, label] of [
+    ["og", "Open Graph"],
+    ["twitter", "Twitter Card"]
+  ]) {
+    const b = before[group];
+    const a = after[group];
+    const dropped = Object.keys(b).filter((k) => !(k in a));
+    if (dropped.length > 0)
+      push(`${group}.removed`, "warn", `${label} tags were removed.`, { before: dropped });
+  }
+  const droppedHreflang = Object.keys(before.hreflang).filter((k) => !(k in after.hreflang));
+  if (droppedHreflang.length > 0)
+    push("hreflang.removed", "warn", "hreflang alternates were removed.", {
+      before: droppedHreflang
+    });
+  if (before.h1.length > 0 && after.h1.length === 0)
+    push("h1.removed", "error", "The <h1> was removed.", { before: before.h1 });
+  if (before.headingOutline.join(">") !== after.headingOutline.join(">"))
+    push("headings.changed", "info", "Heading outline changed.", {
+      before: before.headingOutline.length,
+      after: after.headingOutline.length
+    });
+  if (before.wordCount > 0) {
+    const ratio = after.wordCount / before.wordCount;
+    if (ratio < 0.5)
+      push("content.dropped", "error", "Word count fell by more than half.", {
+        before: before.wordCount,
+        after: after.wordCount
+      });
+  }
+  return findings;
+}
+function diffSite(before, after) {
+  const findings = [];
+  const push = (code, severity, message, extra = {}) => findings.push({ code, severity, route: null, message, ...extra });
+  if (before.robotsTxt?.present && !after.robotsTxt?.present)
+    push("robotstxt.removed", "error", "robots.txt disappeared.");
+  if (before.robotsTxt && after.robotsTxt) {
+    for (const [agent, state] of Object.entries(before.robotsTxt.aiAgents)) {
+      const next = after.robotsTxt.aiAgents[agent];
+      if (state === "allowed" && next === "disallowed")
+        push("aeo.crawler.newly_blocked", "error", `robots.txt now blocks ${agent}.`, { after: agent });
+      if (state === "disallowed" && next === "allowed")
+        push("aeo.crawler.unblocked", "info", `robots.txt now allows ${agent}.`, { after: agent });
+    }
+    const droppedSitemaps = before.robotsTxt.sitemaps.filter(
+      (s) => !after.robotsTxt.sitemaps.includes(s)
+    );
+    if (droppedSitemaps.length > 0)
+      push("robotstxt.sitemap.removed", "warn", `Sitemap declaration removed: ${droppedSitemaps.join(", ")}.`);
+  }
+  if (before.llmsTxt?.present && !after.llmsTxt?.present)
+    push("aeo.llmstxt.removed", "error", "/llms.txt disappeared.");
+  if (before.llmsTxt?.present && after.llmsTxt?.present) {
+    const dropped = before.llmsTxt.sections.filter((s) => !after.llmsTxt.sections.includes(s));
+    if (dropped.length > 0)
+      push("aeo.llmstxt.sections.removed", "warn", `llms.txt sections removed: ${dropped.join(", ")}.`);
+    if (after.llmsTxt.bytes < before.llmsTxt.bytes * 0.5)
+      push("aeo.llmstxt.truncated", "warn", "llms.txt shrank by more than half.", {
+        before: before.llmsTxt.bytes,
+        after: after.llmsTxt.bytes
+      });
+  }
+  return findings;
+}
+function diffSnapshots(before, after) {
+  const findings = diffSite(before.site, after.site);
+  for (const route of Object.keys(before.pages)) {
+    if (!(route in after.pages)) {
+      findings.push({
+        code: "page.removed",
+        severity: "warn",
+        route,
+        message: "Page is no longer present."
+      });
+    }
+  }
+  for (const [route, page] of Object.entries(after.pages)) {
+    const previous = before.pages[route];
+    if (!previous) {
+      findings.push({ code: "page.added", severity: "info", route, message: "New page." });
+      continue;
+    }
+    findings.push(...diffPage(previous, page));
+  }
+  return findings;
+}
+
+// src/rules/guidance.ts
+var GUIDANCE = {
+  "title.missing": {
+    why: "The title is the strongest on-page ranking signal and the clickable line in results. Without one, search engines invent a title from page content, usually badly.",
+    fix: "Add a unique <title> of roughly 50-60 characters that leads with the primary term.",
+    byPlatform: {
+      wordpress: "Set the SEO title in Yoast or Rank Math for this post, or fix the title template under the plugin's Search Appearance settings.",
+      nextjs: "Export `metadata.title` from the route segment, or set a `title.template` in the root layout."
+    }
+  },
+  "title.long": {
+    why: "Titles beyond roughly 60 characters get truncated in results, so the tail of the title does no work.",
+    fix: "Trim to under 60 characters, keeping the distinguishing words at the front."
+  },
+  "description.missing": {
+    why: "Without a meta description the engine writes its own snippet from page text, which is often a nav menu or boilerplate.",
+    fix: "Write a 140-160 character description that states what the page offers.",
+    byPlatform: {
+      wordpress: "Fill the meta description field in the Yoast or Rank Math box below the editor, or set a template for this post type.",
+      nextjs: "Add `description` to the route's exported `metadata` object."
+    }
+  },
+  "canonical.missing": {
+    why: "Without a canonical, duplicate URLs (query strings, pagination, tracking parameters, trailing-slash variants) compete against each other and split ranking signals.",
+    fix: "Emit a self-referencing canonical link on every indexable page.",
+    byPlatform: {
+      wordpress: "Yoast and Rank Math both output canonicals by default \u2014 this usually means the SEO plugin is inactive on this template, or a theme is stripping wp_head().",
+      nextjs: "Set `alternates.canonical` in the route's metadata."
+    }
+  },
+  "h1.missing": {
+    why: "The h1 tells both crawlers and answer engines what the page is about, and it anchors the document outline used for passage extraction.",
+    fix: "Add exactly one h1 that matches the page topic.",
+    byPlatform: {
+      wordpress: "Many themes render the post title as h2 inside archive templates. Check single.php or the block template for this post type."
+    }
+  },
+  "h1.multiple": {
+    why: "Multiple h1 elements make the document outline ambiguous, which weakens passage extraction for AI answers.",
+    fix: "Keep one h1 and demote the rest to h2."
+  },
+  "robots.noindex": {
+    why: "This page is explicitly excluded from search results. If that is unintentional it is invisible traffic loss.",
+    fix: "Remove the noindex directive if the page should rank.",
+    byPlatform: {
+      wordpress: "Check Settings \u2192 Reading for the site-wide discourage option, and the per-post Advanced tab in your SEO plugin."
+    }
+  },
+  "og.title.missing": {
+    why: "Without Open Graph tags, shared links render with whatever the platform can scrape, which is usually wrong.",
+    fix: "Add og:title, og:description, og:image and og:url.",
+    byPlatform: {
+      wordpress: "Enable social meta in Yoast (Social tab) or Rank Math, and set a site-wide fallback image."
+    }
+  },
+  "og.image.missing": {
+    why: "Links without og:image get a plain text card in messaging apps and social feeds, which measurably lowers click-through.",
+    fix: "Add an og:image of at least 1200x630."
+  },
+  "jsonld.missing": {
+    why: "Structured data is how you become eligible for rich results, and it is the most reliable signal answer engines use to identify entities on a page.",
+    fix: "Add JSON-LD appropriate to the page type \u2014 Article for posts, Product for products, LocalBusiness and Organization site-wide.",
+    byPlatform: {
+      wordpress: "Rank Math and Yoast both emit a schema graph. If it is absent, the plugin is off for this template or the theme is not calling wp_head()."
+    }
+  },
+  "jsonld.invalid": {
+    why: "A JSON-LD block that fails to parse is ignored entirely, so any valid markup in the same script tag is lost with it.",
+    fix: "Fix the JSON syntax \u2014 usually an unescaped quote or a trailing comma injected by a template."
+  },
+  "jsonld.required.missing": {
+    why: "Google will not show a rich result when a required property is absent, even though the rest of the markup is valid.",
+    fix: "Add the named properties. Verify with the Rich Results Test before shipping."
+  },
+  "jsonld.oneof.missing": {
+    why: "Some types need at least one of a group of properties to qualify for a rich result.",
+    fix: "Add one of the listed properties."
+  },
+  "jsonld.recommended.missing": {
+    why: "Recommended properties are not required, but they widen the rich result and give answer engines more to work with.",
+    fix: "Add them where you have the data."
+  },
+  "content.thin": {
+    why: "Short pages rarely rank for competitive terms and are almost never cited by answer engines, which need enough context to quote.",
+    fix: "Either expand the page substantively or consolidate it into a stronger one.",
+    byPlatform: {
+      wordpress: "Tag and category archives commonly trip this. Consider noindexing thin archives rather than padding them."
+    }
+  },
+  "images.alt.missing": {
+    why: "Missing alt text is both an accessibility failure and lost context \u2014 image search and multimodal crawlers rely on it.",
+    fix: 'Describe the image in alt, or use alt="" for purely decorative images so it is explicitly marked.',
+    byPlatform: {
+      wordpress: "Set alt text in the Media Library so it applies everywhere the image is reused."
+    }
+  },
+  "aeo.lead.missing": {
+    why: "Answer engines extract and quote the opening passage. A page that starts with a hero image, a nav block or a one-line teaser gives them nothing to lift.",
+    fix: "Open with a self-contained paragraph of 40-80 words that directly answers the page's implied question."
+  },
+  "aeo.lead.long": {
+    why: "A very long opening block gets chunked awkwardly and the quotable part may be split across chunks.",
+    fix: "Front-load a short direct answer, then expand below it."
+  },
+  "robotstxt.missing": {
+    why: "Without robots.txt you have no control over crawler access and no place to declare your sitemap.",
+    fix: "Add a robots.txt at the site root with a Sitemap line.",
+    byPlatform: {
+      wordpress: "WordPress serves a virtual robots.txt; a missing one usually means a plugin or the server is intercepting the request."
+    }
+  },
+  "robotstxt.sitemap.missing": {
+    why: "The sitemap declaration in robots.txt is the primary discovery path for crawlers that did not arrive through Search Console.",
+    fix: "Add a Sitemap line pointing at your sitemap index.",
+    byPlatform: {
+      wordpress: "WordPress core exposes /wp-sitemap.xml; Yoast and Rank Math replace it with their own. Declare whichever is live."
+    }
+  },
+  "aeo.crawler.blocked": {
+    why: "A blocked AI crawler cannot fetch your pages, so your site cannot be cited in that assistant's answers. This is sometimes deliberate \u2014 worth confirming it is.",
+    fix: "Remove the Disallow for agents you want citing you, and keep it for the ones you do not.",
+    byPlatform: {
+      wordpress: "Some security and SEO plugins add AI crawler blocks by default. Check the plugin that manages your robots.txt."
+    }
+  },
+  "aeo.llmstxt.missing": {
+    why: "llms.txt is an emerging convention giving assistants a curated map of your site. Adoption is still early, so treat this as an opportunity rather than a defect.",
+    fix: "Publish /llms.txt with a short site summary and links to your most important pages."
+  },
+  "hreflang.missing": {
+    why: "The rest of the site declares language alternates but this page does not, so search engines treat it as having no localised counterparts and may serve the wrong language version.",
+    fix: "Add the full set of hreflang links, including a self-reference.",
+    byPlatform: {
+      wordpress: "Usually a template the translation plugin does not cover. Check that WPML or Polylang is active for this post type.",
+      nextjs: "Set `alternates.languages` in the route's metadata, or generate it in the shared layout."
+    }
+  },
+  "hreflang.nonreciprocal": {
+    why: "Google requires hreflang annotations to be reciprocal. If page A points at B but B does not point back at A, the entire annotation is discarded \u2014 not just the one link \u2014 so the whole language cluster stops working.",
+    fix: "Make every page in a language group list every other page in that group, including itself."
+  },
+  "hreflang.self.missing": {
+    why: "Each page in an hreflang set should reference itself. Without it, some engines will not associate the page with its own language.",
+    fix: "Add an hreflang link pointing at this page's own URL with its own language code."
+  },
+  "hreflang.xdefault.missing": {
+    why: "x-default tells engines which version to serve to users whose language matches none of your alternates. Without it, that choice is made for you.",
+    fix: "Add an x-default link pointing at your default or language-selection page."
+  },
+  "hreflang.invalid": {
+    why: "A malformed language code makes the annotation invalid and it is ignored.",
+    fix: "Use ISO 639-1 language codes, optionally with an ISO 3166-1 Alpha 2 region \u2014 `en`, `ml`, `en-IN` \u2014 or `x-default`."
+  },
+  "hreflang.noindex.target": {
+    why: "An hreflang alternate that is noindexed cannot be served as a language variant, which invalidates that link in the cluster.",
+    fix: "Either remove the noindex from the target or drop it from the hreflang set."
+  },
+  "duplicate.title": {
+    why: "Identical titles across pages make them compete for the same queries and signal thin or templated content.",
+    fix: "Make each title unique, usually by including the distinguishing attribute of the page.",
+    byPlatform: {
+      wordpress: "Almost always a title template problem \u2014 check Search Appearance for the affected post type or archive."
+    }
+  },
+  "duplicate.description": {
+    why: "Repeated descriptions get discarded by search engines, which then write their own snippet.",
+    fix: "Vary the description per page, or leave it off and let the engine choose rather than repeating boilerplate."
+  },
+  "duplicate.canonical": {
+    why: "Several pages pointing at one canonical means those pages are declaring themselves duplicates and will not rank independently. Correct for pagination and filters, a serious bug elsewhere.",
+    fix: "Confirm each canonical is self-referencing unless consolidation is intended.",
+    byPlatform: {
+      wordpress: "A common symptom of a plugin canonicalising every archive page to the parent."
+    }
+  },
+  "canonical.offsite": {
+    why: "The canonical points at a different host, which tells search engines to index that host instead of this one. A staging or CDN hostname leaking into canonicals removes the live site from results.",
+    fix: "Point canonicals at the production origin. If the content is deliberately syndicated from another domain, this is correct and the rule can be switched off in config.",
+    byPlatform: {
+      wordpress: "Check the Site Address (URL) setting, and any WP_HOME or WP_SITEURL override in wp-config.php, on the environment that built this.",
+      nextjs: "Check `metadataBase` \u2014 a wrong or missing value makes every relative canonical resolve against the wrong origin."
+    }
+  },
+  "canonical.crosspath": {
+    why: "The canonical points at a different path than the page itself, so this URL is asking not to be indexed in favour of another.",
+    fix: "Verify the target is correct. If this page should rank on its own, make the canonical self-referencing."
+  }
+};
+function detectPlatform(generators, urls = []) {
+  const gen = generators.filter(Boolean).join(" ").toLowerCase();
+  if (gen.includes("wordpress")) return "wordpress";
+  if (gen.includes("drupal")) return "drupal";
+  if (gen.includes("wix")) return "wix";
+  if (gen.includes("squarespace")) return "squarespace";
+  if (gen.includes("webflow")) return "webflow";
+  if (gen.includes("shopify")) return "shopify";
+  if (gen.includes("next.js")) return "nextjs";
+  const joined = urls.join(" ").toLowerCase();
+  if (joined.includes("/wp-content/") || joined.includes("/wp-json/")) return "wordpress";
+  if (joined.includes("/_next/")) return "nextjs";
+  if (joined.includes("cdn.shopify.com")) return "shopify";
+  return "unknown";
+}
+function withGuidance(finding, platform = "unknown") {
+  const guidance = GUIDANCE[finding.code];
+  if (!guidance) return finding;
+  return {
+    ...finding,
+    detail: guidance.why,
+    fix: guidance.byPlatform?.[platform] ?? guidance.fix
+  };
+}
+
+// src/report.ts
+var import_picocolors = __toESM(require("picocolors"), 1);
+var ORDER = { error: 0, warn: 1, info: 2 };
+function applyConfig(findings, config = {}) {
+  const overrides = config.severity ?? {};
+  const out = [];
+  for (const finding of findings) {
+    const override = overrides[finding.code];
+    if (override === "off") continue;
+    out.push(override ? { ...finding, severity: override } : finding);
+  }
+  return out.sort(
+    (a, b) => ORDER[a.severity] - ORDER[b.severity] || (a.route ?? "").localeCompare(b.route ?? "")
+  );
+}
+function summarize(findings) {
+  return {
+    error: findings.filter((f) => f.severity === "error").length,
+    warn: findings.filter((f) => f.severity === "warn").length,
+    info: findings.filter((f) => f.severity === "info").length
+  };
+}
+function shouldFail(findings, failOn) {
+  const threshold = ORDER[failOn];
+  if (threshold === void 0) {
+    throw new Error(`Unknown severity "${failOn}". Expected one of: error, warn, info.`);
+  }
+  return findings.some((f) => ORDER[f.severity] <= threshold);
+}
+var BADGE = {
+  error: (s) => import_picocolors.default.red(s),
+  warn: (s) => import_picocolors.default.yellow(s),
+  info: (s) => import_picocolors.default.dim(s)
+};
+function formatPretty(findings) {
+  if (findings.length === 0) return import_picocolors.default.green("No SEO/AEO changes or issues found.");
+  const byRoute = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    const key = finding.route ?? "(site-wide)";
+    if (!byRoute.has(key)) byRoute.set(key, []);
+    byRoute.get(key).push(finding);
+  }
+  const lines = [];
+  for (const [route, group] of byRoute) {
+    lines.push(import_picocolors.default.bold(route));
+    for (const f of group) {
+      lines.push(`  ${BADGE[f.severity](f.severity.padEnd(5))} ${f.message} ${import_picocolors.default.dim(f.code)}`);
+    }
+    lines.push("");
+  }
+  const s = summarize(findings);
+  lines.push(`${s.error} error, ${s.warn} warning, ${s.info} info`);
+  return lines.join("\n");
+}
+function formatJson(findings) {
+  return JSON.stringify({ schemaVersion: 1, summary: summarize(findings), findings }, null, 2);
+}
+var escapeCell = (value) => value.replace(/\|/g, "\\|");
+function formatMarkdown(findings) {
+  const s = summarize(findings);
+  if (findings.length === 0) return "### pagetrace\n\nNo SEO/AEO changes or issues found.";
+  const rows = findings.map(
+    (f) => `| ${f.severity} | \`${escapeCell(f.route ?? "\u2014")}\` | ${escapeCell(f.message)} | \`${f.code}\` |`
+  );
+  return [
+    "### pagetrace",
+    "",
+    `${s.error} error \xB7 ${s.warn} warning \xB7 ${s.info} info`,
+    "",
+    "| Severity | Route | Finding | Code |",
+    "| --- | --- | --- | --- |",
+    ...rows
+  ].join("\n");
+}
+function formatGithub(findings) {
+  return findings.filter((f) => f.severity !== "info").map((f) => {
+    const level = f.severity === "error" ? "error" : "warning";
+    return `::${level} title=${f.code}::${f.route ?? "site"} \u2014 ${f.message}`;
+  }).join("\n");
+}
+function aggregate(findings) {
+  const map = /* @__PURE__ */ new Map();
+  for (const finding of findings) {
+    const key = `${finding.code}::${finding.message}`;
+    const existing = map.get(key);
+    if (existing) {
+      existing.count += 1;
+      if (finding.route) existing.routes.push(finding.route);
+      continue;
+    }
+    map.set(key, {
+      code: finding.code,
+      severity: finding.severity,
+      count: 1,
+      routes: finding.route ? [finding.route] : [],
+      message: finding.message,
+      detail: finding.detail,
+      fix: finding.fix
+    });
+  }
+  return [...map.values()].sort(
+    (a, b) => ORDER[a.severity] - ORDER[b.severity] || b.count - a.count
+  );
+}
+var PLATFORM_LABEL = {
+  wordpress: "WordPress",
+  nextjs: "Next.js",
+  shopify: "Shopify",
+  webflow: "Webflow",
+  wix: "Wix",
+  squarespace: "Squarespace",
+  drupal: "Drupal",
+  unknown: "Unknown platform"
+};
+function isTemplateWide(group, pageCount) {
+  return pageCount >= 5 && group.routes.length >= Math.ceil(pageCount * 0.8);
+}
+function countIssues(groups) {
+  const blank = () => ({ error: 0, warn: 0, info: 0 });
+  const issues = blank();
+  const instances = blank();
+  for (const group of groups) {
+    issues[group.severity] += 1;
+    instances[group.severity] += group.count;
+  }
+  return { issues, instances, total: groups.length };
+}
+function sampleRoutes(routes, limit = 5) {
+  if (routes.length === 0) return "site-wide";
+  const shown = routes.slice(0, limit).join(", ");
+  return routes.length > limit ? `${shown} +${routes.length - limit} more` : shown;
+}
+function formatAuditPretty(groups, meta) {
+  const lines = [
+    import_picocolors.default.bold(meta.target),
+    import_picocolors.default.dim(`${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages \xB7 ${meta.generatedAt}`),
+    ""
+  ];
+  if (groups.length === 0) {
+    lines.push(import_picocolors.default.green("No issues found."));
+    return lines.join("\n");
+  }
+  for (const group of groups) {
+    const scope = isTemplateWide(group, meta.pageCount) ? import_picocolors.default.dim(`(${group.count} pages \u2014 one template fix)`) : import_picocolors.default.dim(`(${group.count})`);
+    lines.push(`${BADGE[group.severity](group.severity.toUpperCase())} ${import_picocolors.default.bold(group.message)} ${scope}`);
+    if (group.detail) lines.push(`  ${group.detail}`);
+    if (group.fix) lines.push(`  ${import_picocolors.default.cyan("Fix:")} ${group.fix}`);
+    if (group.routes.length > 0) lines.push(`  ${import_picocolors.default.dim(sampleRoutes(group.routes))}`);
+    lines.push("");
+  }
+  const { issues, instances, total } = countIssues(groups);
+  lines.push(
+    `${total} issue${total === 1 ? "" : "s"}: ${issues.error} error, ${issues.warn} warning, ${issues.info} info`
+  );
+  lines.push(
+    import_picocolors.default.dim(
+      `across ${instances.error + instances.warn + instances.info} page findings on ${meta.pageCount} pages`
+    )
+  );
+  return lines.join("\n");
+}
+function formatAuditMarkdown(groups, meta) {
+  const lines = [
+    `# SEO & AEO audit \u2014 ${meta.target}`,
+    "",
+    `${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages crawled \xB7 ${meta.generatedAt}`,
+    ""
+  ];
+  if (groups.length === 0) {
+    lines.push("No issues found.");
+    return lines.join("\n");
+  }
+  for (const group of groups) {
+    lines.push(`## ${group.message}`, "");
+    const scope = isTemplateWide(group, meta.pageCount) ? `affects ${group.count} pages \u2014 one template fix` : `affects ${group.count} page${group.count === 1 ? "" : "s"}`;
+    lines.push(`**${group.severity.toUpperCase()}** \xB7 ${scope} \xB7 \`${group.code}\``, "");
+    if (group.detail) lines.push(group.detail, "");
+    if (group.fix) lines.push(`**Fix.** ${group.fix}`, "");
+    if (group.routes.length > 0) {
+      lines.push("<details><summary>Affected pages</summary>", "");
+      for (const route of group.routes.slice(0, 50)) lines.push(`- \`${route}\``);
+      if (group.routes.length > 50) lines.push(`- \u2026and ${group.routes.length - 50} more`);
+      lines.push("", "</details>", "");
+    }
+  }
+  return lines.join("\n");
+}
+var escapeHtml = (value) => value.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+function formatAuditHtml(groups, meta) {
+  const { issues } = countIssues(groups);
+  const cards = groups.map((group) => {
+    const scope = isTemplateWide(group, meta.pageCount) ? `<span class="tmpl">template-wide</span>` : "";
+    const routes = group.routes.length > 0 ? `<details><summary>${group.routes.length} affected page${group.routes.length === 1 ? "" : "s"}</summary><ul>${group.routes.slice(0, 100).map((r) => `<li><code>${escapeHtml(r)}</code></li>`).join("")}</ul></details>` : "";
+    return `<article class="f ${group.severity}">
+  <header><span class="sev">${group.severity}</span><h2>${escapeHtml(group.message)}</h2>${scope}<span class="count">${group.count}</span></header>
+  ${group.detail ? `<p>${escapeHtml(group.detail)}</p>` : ""}
+  ${group.fix ? `<p class="fix"><strong>Fix.</strong> ${escapeHtml(group.fix)}</p>` : ""}
+  ${routes}
+  <code class="code">${escapeHtml(group.code)}</code>
+</article>`;
+  }).join("\n");
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>SEO &amp; AEO audit \u2014 ${escapeHtml(meta.target)}</title>
+<style>
+:root{--fg:#16181d;--muted:#6b7280;--line:#e5e7eb;--err:#b42318;--warn:#b54708;--info:#475467;--bg:#fff}
+*{box-sizing:border-box}
+body{margin:0;padding:48px 24px;font:16px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;color:var(--fg);background:var(--bg)}
+main{max-width:820px;margin:0 auto}
+h1{font-size:28px;margin:0 0 6px;letter-spacing:-.02em}
+.meta{color:var(--muted);font-size:14px;margin:0 0 28px}
+.totals{display:flex;gap:12px;margin:0 0 36px;padding:0;list-style:none}
+.totals li{flex:1;border:1px solid var(--line);border-radius:10px;padding:14px 16px}
+.totals b{display:block;font-size:26px;line-height:1.2}
+.totals span{color:var(--muted);font-size:13px;text-transform:uppercase;letter-spacing:.06em}
+.f{border:1px solid var(--line);border-left-width:4px;border-radius:10px;padding:18px 20px;margin:0 0 16px}
+.f.error{border-left-color:var(--err)} .f.warn{border-left-color:var(--warn)} .f.info{border-left-color:var(--info)}
+.f header{display:flex;align-items:baseline;gap:10px;margin-bottom:8px}
+.f h2{font-size:17px;margin:0;flex:1;letter-spacing:-.01em}
+.sev{font-size:11px;text-transform:uppercase;letter-spacing:.08em;font-weight:700}
+.error .sev{color:var(--err)} .warn .sev{color:var(--warn)} .info .sev{color:var(--info)}
+.count{font-variant-numeric:tabular-nums;color:var(--muted);font-size:14px}
+.tmpl{font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--muted);border:1px solid var(--line);border-radius:99px;padding:2px 8px}
+.f p{margin:0 0 10px;font-size:15px}
+.fix{color:#065f46}
+details{font-size:14px;margin:10px 0}
+summary{cursor:pointer;color:var(--muted)}
+details ul{margin:8px 0 0;padding-left:20px;max-height:260px;overflow:auto}
+.code{font-size:12px;color:var(--muted)}
+footer{margin-top:40px;color:var(--muted);font-size:13px;border-top:1px solid var(--line);padding-top:16px}
+</style></head>
+<body><main>
+<h1>SEO &amp; AEO audit</h1>
+<p class="meta">${escapeHtml(meta.target)} \xB7 ${PLATFORM_LABEL[meta.platform]} \xB7 ${meta.pageCount} pages crawled \xB7 ${escapeHtml(meta.generatedAt)}</p>
+<ul class="totals">
+  <li><b>${issues.error}</b><span>Errors</span></li>
+  <li><b>${issues.warn}</b><span>Warnings</span></li>
+  <li><b>${issues.info}</b><span>Notes</span></li>
+</ul>
+${cards || "<p>No issues found.</p>"}
+<footer>Generated by pagetrace. Findings are heuristic; verify structured data with Google&rsquo;s Rich Results Test before shipping fixes.</footer>
+</main></body></html>`;
+}
+
+// src/snapshot.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+
+// src/extract.ts
+var import_node_html_parser = require("node-html-parser");
+var HEADING_TAGS = /* @__PURE__ */ new Set(["H1", "H2", "H3", "H4", "H5", "H6"]);
+var NON_CONTENT = /* @__PURE__ */ new Set(["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE", "SVG"]);
+function text(el) {
+  if (!el) return null;
+  const value = el.textContent.replace(/\s+/g, " ").trim();
+  return value.length > 0 ? value : null;
+}
+function metaContent(root, name) {
+  for (const el of root.querySelectorAll("meta")) {
+    if (el.getAttribute("name")?.trim().toLowerCase() !== name) continue;
+    const value = el.getAttribute("content")?.trim();
+    if (value) return value;
+  }
+  return null;
+}
+function hasRel(el, rel) {
+  const value = el.getAttribute("rel");
+  if (!value) return false;
+  return value.trim().toLowerCase().split(/\s+/).includes(rel);
+}
+function linkHref(root, rel) {
+  for (const el of root.querySelectorAll("link")) {
+    if (!hasRel(el, rel)) continue;
+    const href = el.getAttribute("href")?.trim();
+    if (href) return href;
+  }
+  return null;
+}
+function metaGroup(root, prefix) {
+  const out = {};
+  for (const el of root.querySelectorAll("meta")) {
+    const key = el.getAttribute("property") ?? el.getAttribute("name");
+    if (!key || !key.toLowerCase().startsWith(`${prefix}:`)) continue;
+    const content = el.getAttribute("content")?.trim();
+    if (!content) continue;
+    out[key.toLowerCase()] = content;
+  }
+  return out;
+}
+function hreflangMap(root) {
+  const out = {};
+  for (const el of root.querySelectorAll("link")) {
+    if (!hasRel(el, "alternate")) continue;
+    const lang = el.getAttribute("hreflang");
+    const href = el.getAttribute("href");
+    if (lang && href) out[lang.toLowerCase()] = href.trim();
+  }
+  return out;
+}
+function flattenJsonLd(node, out) {
+  if (Array.isArray(node)) {
+    for (const item of node) flattenJsonLd(item, out);
+    return;
+  }
+  if (typeof node !== "object" || node === null) return;
+  const obj = node;
+  if ("@graph" in obj) {
+    flattenJsonLd(obj["@graph"], out);
+    const rest = Object.keys(obj).filter((k) => k !== "@graph" && k !== "@context");
+    if (rest.length === 0) return;
+  }
+  const rawType = obj["@type"];
+  const type = Array.isArray(rawType) ? String(rawType[0]) : rawType ? String(rawType) : null;
+  if (!type) return;
+  out.push({
+    type,
+    ...typeof obj["@id"] === "string" ? { id: obj["@id"] } : {},
+    properties: Object.keys(obj).filter((k) => !k.startsWith("@")).sort()
+  });
+}
+function extractJsonLd(root) {
+  const entities = [];
+  for (const script of root.querySelectorAll("script")) {
+    if (script.getAttribute("type")?.trim().toLowerCase() !== "application/ld+json") continue;
+    try {
+      flattenJsonLd(JSON.parse(script.textContent), entities);
+    } catch {
+      entities.push({ type: "__parse_error__", properties: [] });
+    }
+  }
+  return entities;
+}
+function countWords(root) {
+  const body = root.querySelector("body") ?? root;
+  const clone = (0, import_node_html_parser.parse)(body.outerHTML);
+  for (const tag of NON_CONTENT) {
+    for (const el of clone.querySelectorAll(tag.toLowerCase())) el.remove();
+  }
+  const words = clone.textContent.replace(/\s+/g, " ").trim();
+  return words.length === 0 ? 0 : words.split(" ").length;
+}
+function leadAnswer(root) {
+  const scope = root.querySelector("main") ?? root.querySelector("article") ?? root.querySelector("body") ?? root;
+  const candidates = scope.querySelectorAll("h1, p").filter((el) => !el.closest("header, nav, footer, aside"));
+  const firstH1 = candidates.findIndex((el) => el.tagName?.toUpperCase() === "H1");
+  for (const el of candidates.slice(firstH1 + 1)) {
+    if (el.tagName?.toUpperCase() !== "P") continue;
+    const value = text(el);
+    if (!value) continue;
+    const words = value.split(" ").length;
+    if (words >= 8) return words;
+  }
+  return 0;
+}
+function extractPage(html, route) {
+  const root = (0, import_node_html_parser.parse)(html, { blockTextElements: { script: true, style: true } });
+  const headings = [];
+  const h1 = [];
+  for (const el of root.querySelectorAll("h1, h2, h3, h4, h5, h6")) {
+    const tag = el.tagName?.toUpperCase();
+    if (!tag || !HEADING_TAGS.has(tag)) continue;
+    headings.push(tag.toLowerCase());
+    if (tag === "H1") {
+      const value = text(el);
+      if (value) h1.push(value);
+    }
+  }
+  const imgs = root.querySelectorAll("img");
+  const missingAlt = imgs.filter((img) => {
+    const alt = img.getAttribute("alt");
+    return alt === void 0 || alt === null;
+  }).length;
+  return {
+    route,
+    title: text(root.querySelector("title")),
+    description: metaContent(root, "description"),
+    canonical: linkHref(root, "canonical"),
+    robots: metaContent(root, "robots")?.toLowerCase() ?? null,
+    og: metaGroup(root, "og"),
+    twitter: metaGroup(root, "twitter"),
+    hreflang: hreflangMap(root),
+    h1,
+    headingOutline: headings,
+    jsonLd: extractJsonLd(root).sort((a, b) => a.type.localeCompare(b.type)),
+    wordCount: countWords(root),
+    images: { total: imgs.length, missingAlt },
+    leadAnswerWords: leadAnswer(root),
+    generator: metaContent(root, "generator")
+  };
+}
+function extractRobotsTxt(body, agents) {
+  const sitemaps = [];
+  const groups = [];
+  let current = null;
+  let lastWasAgent = false;
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = rawLine.split("#")[0].trim();
+    if (!line) continue;
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const field = line.slice(0, idx).trim().toLowerCase();
+    const value = line.slice(idx + 1).trim();
+    if (field === "sitemap") {
+      sitemaps.push(value);
+      continue;
+    }
+    if (field === "user-agent") {
+      if (!current || !lastWasAgent) {
+        current = { agents: [], disallowAll: false };
+        groups.push(current);
+      }
+      current.agents.push(value.toLowerCase());
+      lastWasAgent = true;
+      continue;
+    }
+    lastWasAgent = false;
+    if (field === "disallow" && current && value === "/") current.disallowAll = true;
+    if (field === "allow" && current && value === "/") current.disallowAll = false;
+  }
+  const aiAgents = {};
+  for (const agent of agents) {
+    const lower = agent.toLowerCase();
+    const specific = groups.find((g) => g.agents.includes(lower));
+    const wildcard = groups.find((g) => g.agents.includes("*"));
+    const group = specific ?? wildcard;
+    aiAgents[agent] = group?.disallowAll ? "disallowed" : "allowed";
+  }
+  return { present: true, aiAgents, sitemaps };
+}
+function extractLlmsTxt(body) {
+  const sections = body.split(/\r?\n/).filter((line) => line.startsWith("## ")).map((line) => line.slice(3).trim());
+  return { present: true, sections, bytes: Buffer.byteLength(body, "utf8") };
+}
+var XML_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'"
+};
+function decodeXml(value) {
+  return value.replace(/&(?:#(\d+)|#x([0-9a-f]+)|([a-z]+));/gi, (match, dec, hex, name) => {
+    if (dec) return String.fromCodePoint(Number(dec));
+    if (hex) return String.fromCodePoint(parseInt(hex, 16));
+    return XML_ENTITIES[String(name).toLowerCase()] ?? match;
+  });
+}
+function extractSitemapUrls(xml) {
+  const pattern = /<loc>\s*(?:<!\[CDATA\[([\s\S]*?)\]\]>|([^<]*?))\s*<\/loc>/gi;
+  return [...xml.matchAll(pattern)].map((m) => (m[1] !== void 0 ? m[1] : decodeXml(m[2] ?? "")).trim()).filter((url) => url.length > 0);
+}
+
+// src/snapshot.ts
+function routeFromFilePath(root, filePath) {
+  const rel = (0, import_node_path.relative)(root, filePath).split(import_node_path.sep).join("/");
+  const withoutExt = rel.replace(/\.html?$/i, "");
+  const route = withoutExt === "index" ? "/" : `/${withoutExt.replace(/\/index$/, "")}`;
+  return route === "//" ? "/" : route;
+}
+function routeFromUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const path = parsed.pathname.replace(/\/+$/, "");
+    return path === "" ? "/" : path;
+  } catch {
+    return url;
+  }
+}
+function shouldIgnore(route, patterns = []) {
+  return patterns.some(
+    (pattern) => pattern.endsWith("*") ? route.startsWith(pattern.slice(0, -1)) : route === pattern
+  );
+}
+async function walkHtml(dir, acc = []) {
+  for (const entry of await (0, import_promises.readdir)(dir, { withFileTypes: true })) {
+    const full = (0, import_node_path.join)(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      await walkHtml(full, acc);
+    } else if (/\.html?$/i.test(entry.name)) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+var DEFAULT_TIMEOUT_MS = 15e3;
+async function fetchText(url, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  let response;
+  try {
+    response = await fetch(url, {
+      signal: AbortSignal.timeout(timeoutMs),
+      headers: { "user-agent": "pagetrace (+https://npmjs.com/package/pagetrace)" }
+    });
+  } catch (cause) {
+    throw new Error(`Could not reach ${url}: ${cause.message}`, { cause });
+  }
+  if (response.status === 404 || response.status === 410) return null;
+  if (!response.ok) throw new Error(`Could not reach ${url}: HTTP ${response.status}.`);
+  return await response.text();
+}
+function tryFetchText(url, timeoutMs) {
+  return fetchText(url, timeoutMs).catch(() => null);
+}
+async function snapshotFromDir(dir, config = {}) {
+  const files = await walkHtml(dir);
+  const pages = {};
+  for (const file of files.sort()) {
+    const route = routeFromFilePath(dir, file);
+    if (shouldIgnore(route, config.ignoreRoutes)) continue;
+    if (route in pages) {
+      console.error(`pagetrace: ${file} maps to ${route}, already taken. Skipping.`);
+      continue;
+    }
+    pages[route] = extractPage(await (0, import_promises.readFile)(file, "utf8"), route);
+  }
+  const agents = config.aiAgents ?? DEFAULT_AI_AGENTS;
+  const site = {
+    origin: config.siteUrl ? new URL(config.siteUrl).origin : null,
+    robotsTxt: null,
+    llmsTxt: null
+  };
+  const robots = await (0, import_promises.readFile)((0, import_node_path.join)(dir, "robots.txt"), "utf8").catch(() => null);
+  if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
+  const llms = await (0, import_promises.readFile)((0, import_node_path.join)(dir, "llms.txt"), "utf8").catch(() => null);
+  if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
+var MAX_NESTED_SITEMAPS = 50;
+async function snapshotFromOrigin(origin, options = {}) {
+  const base = new URL(origin);
+  const agents = options.aiAgents ?? DEFAULT_AI_AGENTS;
+  const timeout = options.timeout;
+  const site = { origin: base.origin, robotsTxt: null, llmsTxt: null };
+  const limit = options.limit ?? 200;
+  const robots = await fetchText(new URL("/robots.txt", base).href, timeout);
+  if (robots !== null) site.robotsTxt = extractRobotsTxt(robots, agents);
+  const llms = await fetchText(new URL("/llms.txt", base).href, timeout);
+  if (llms !== null) site.llmsTxt = extractLlmsTxt(llms);
+  const sitemapUrls = site.robotsTxt?.sitemaps.length ? site.robotsTxt.sitemaps : [
+    new URL("/sitemap.xml", base).href,
+    new URL("/sitemap_index.xml", base).href,
+    new URL("/wp-sitemap.xml", base).href
+  ];
+  const discovered = /* @__PURE__ */ new Set();
+  const fetched = /* @__PURE__ */ new Set();
+  let nestedFetches = 0;
+  for (const sitemapUrl of sitemapUrls) {
+    if (discovered.size >= limit) break;
+    if (discovered.size > 0 && !site.robotsTxt?.sitemaps.length) break;
+    if (fetched.has(sitemapUrl)) continue;
+    fetched.add(sitemapUrl);
+    const xml = site.robotsTxt?.sitemaps.length ? await fetchText(sitemapUrl, timeout) : await tryFetchText(sitemapUrl, timeout);
+    if (!xml) continue;
+    for (const loc of extractSitemapUrls(xml)) {
+      if (discovered.size >= limit) break;
+      if (!/\.xml(\.gz)?($|\?)/i.test(loc)) {
+        discovered.add(loc);
+        continue;
+      }
+      if (/\.gz($|\?)/i.test(loc)) continue;
+      if (nestedFetches >= MAX_NESTED_SITEMAPS || fetched.has(loc)) continue;
+      fetched.add(loc);
+      nestedFetches += 1;
+      const nested = await tryFetchText(loc, timeout);
+      if (nested) for (const url of extractSitemapUrls(nested)) discovered.add(url);
+    }
+  }
+  if (discovered.size === 0) discovered.add(base.href);
+  const targets = [...discovered].filter((url) => {
+    try {
+      return new URL(url).origin === base.origin;
+    } catch {
+      return false;
+    }
+  }).filter((url) => !shouldIgnore(routeFromUrl(url), options.ignoreRoutes)).slice(0, limit);
+  const pages = {};
+  const concurrency = Math.max(1, options.concurrency ?? 5);
+  const queue = [...targets];
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+      while (queue.length > 0) {
+        const url = queue.shift();
+        const html = await fetchText(url, timeout);
+        if (html === null) continue;
+        const route = routeFromUrl(url);
+        pages[route] = extractPage(html, route);
+      }
+    })
+  );
+  return { schemaVersion: 1, createdAt: (/* @__PURE__ */ new Date()).toISOString(), site, pages };
+}
+
+// src/cli.ts
+var DEFAULT_LOCKFILE = "pagetrace.lock.json";
+var DEFAULT_CONFIG = "pagetrace.config.json";
+var SEVERITIES = ["error", "warn", "info"];
+function parseFailOn(value, allowNever) {
+  const expected = [...SEVERITIES, ...allowNever ? ["never"] : []].join(" | ");
+  if (typeof value !== "string") throw new Error(`--fail-on needs a value. Expected ${expected}.`);
+  if (allowNever && value === "never") return "never";
+  if (SEVERITIES.includes(value)) return value;
+  throw new Error(`Invalid --fail-on "${value}". Expected ${expected}.`);
+}
+async function loadConfig(path = DEFAULT_CONFIG) {
+  try {
+    return JSON.parse(await (0, import_promises2.readFile)(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+async function build(flags, config) {
+  if (flags.dir) return snapshotFromDir(flags.dir, config);
+  if (flags.url)
+    return snapshotFromOrigin(flags.url, {
+      ...config,
+      limit: flags.limit,
+      concurrency: flags.concurrency
+    });
+  throw new Error("Provide a source: --dir <build directory> or --url <origin>.");
+}
+function render(findings, format) {
+  switch (format) {
+    case "json":
+      return formatJson(findings);
+    case "markdown":
+      return formatMarkdown(findings);
+    case "github":
+      return formatGithub(findings);
+    default:
+      return formatPretty(findings);
+  }
+}
+var cli = (0, import_cac.cac)("pagetrace");
+cli.command("snapshot", "Record the current SEO/AEO surface to a lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--out <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).action(async (flags) => {
+  const config = await loadConfig(flags.config);
+  const snapshot = await build(flags, config);
+  await (0, import_promises2.writeFile)(flags.out, `${JSON.stringify(snapshot, null, 2)}
+`, "utf8");
+  const count = Object.keys(snapshot.pages).length;
+  console.log(import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${count} page${count === 1 ? "" : "s"}.`));
+});
+cli.command("check", "Compare the current surface against the lockfile").option("--dir <dir>", "Directory of built HTML").option("--url <origin>", "Live origin to crawl").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--lockfile <file>", "Lockfile path", { default: DEFAULT_LOCKFILE }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | github", { default: "pretty" }).option("--fail-on <severity>", "error | warn | info", { default: "error" }).option("--audit", "Also run absolute rules, not just the diff", { default: true }).option("--update", "Write the new state to the lockfile after reporting").action(async (flags) => {
+  const failOn = parseFailOn(flags.failOn, false);
+  const config = await loadConfig(flags.config);
+  const next = await build(flags, config);
+  let previous = null;
+  try {
+    previous = JSON.parse(await (0, import_promises2.readFile)(flags.lockfile, "utf8"));
+  } catch {
+    previous = null;
+  }
+  if (!previous) {
+    console.error(
+      import_picocolors2.default.yellow(`No lockfile at ${flags.lockfile}. Run \`pagetrace snapshot\` first to set a baseline.`)
+    );
+  }
+  const raw = [
+    ...previous ? diffSnapshots(previous, next) : [],
+    ...flags.audit ? auditSnapshot(next, config) : []
+  ];
+  const findings = applyConfig(raw, config);
+  console.log(render(findings, flags.format));
+  if (flags.update) {
+    await (0, import_promises2.writeFile)(flags.lockfile, `${JSON.stringify(next, null, 2)}
+`, "utf8");
+    console.error(import_picocolors2.default.dim(`Updated ${flags.lockfile}.`));
+  }
+  const summary = summarize(findings);
+  if (previous && shouldFail(findings, failOn)) {
+    console.error(
+      import_picocolors2.default.red(`
+Failing: ${summary.error} error, ${summary.warn} warning (--fail-on ${failOn}).`)
+    );
+    process.exitCode = 1;
+  }
+});
+cli.command("audit", "Audit a site as it stands, with explanations and fixes").option("--url <origin>", "Live origin to crawl").option("--dir <dir>", "Directory of built HTML").option("--limit <n>", "Max pages to crawl", { default: 200 }).option("--concurrency <n>", "Parallel requests", { default: 5 }).option("--config <file>", "Config file", { default: DEFAULT_CONFIG }).option("--format <format>", "pretty | json | markdown | html", { default: "pretty" }).option("--out <file>", "Write the report to a file instead of stdout").option("--fail-on <severity>", "error | warn | info | never", { default: "never" }).action(async (flags) => {
+  const failOn = parseFailOn(flags.failOn, true);
+  const config = await loadConfig(flags.config);
+  const snapshot = await build(flags, config);
+  const pages = Object.values(snapshot.pages);
+  if (pages.length === 0) {
+    console.error(
+      import_picocolors2.default.yellow(
+        "No pages found. Check that the sitemap is reachable, or pass --dir with pre-rendered HTML."
+      )
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const platform = detectPlatform(
+    pages.map((p) => p.generator),
+    pages.flatMap((p) => Object.values(p.og))
+  );
+  const findings = applyConfig(auditSnapshot(snapshot, config), config).map(
+    (f) => withGuidance(f, platform)
+  );
+  const groups = aggregate(findings);
+  const meta = {
+    target: flags.url ?? flags.dir ?? "site",
+    platform,
+    pageCount: pages.length,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10)
+  };
+  const output = flags.format === "json" ? JSON.stringify({ schemaVersion: 1, meta, summary: summarize(findings), groups }, null, 2) : flags.format === "markdown" ? formatAuditMarkdown(groups, meta) : flags.format === "html" ? formatAuditHtml(groups, meta) : formatAuditPretty(groups, meta);
+  if (flags.out) {
+    await (0, import_promises2.writeFile)(flags.out, `${output}
+`, "utf8");
+    console.log(import_picocolors2.default.green(`Wrote ${flags.out} \u2014 ${groups.length} issue types across ${pages.length} pages.`));
+  } else {
+    console.log(output);
+  }
+  if (failOn !== "never" && shouldFail(findings, failOn)) {
+    process.exitCode = 1;
+  }
+});
+cli.help();
+cli.version("0.2.0");
+async function main() {
+  try {
+    cli.parse(process.argv, { run: false });
+    await cli.runMatchedCommand();
+  } catch (error) {
+    console.error(import_picocolors2.default.red(error.message));
+    process.exitCode = 1;
+  }
+}
+void main();
+//# sourceMappingURL=cli.cjs.map