geo-checker 0.1.0

package/dist/cli.js

@@ -0,0 +1,1357 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { cac } from "cac";
+import kleur2 from "kleur";
+
+// src/context.ts
+import { load as cheerioLoad } from "cheerio";
+
+// src/fetcher/static.ts
+import { request } from "undici";
+var DEFAULT_UA = "geo-checker/0.1.0 (+https://github.com/BaRam-OSS/geo-checker)";
+function normalizeHeaders(input) {
+  const out = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (v == null) continue;
+    out[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : v;
+  }
+  return out;
+}
+async function fetchStatic(url, opts = {}) {
+  const maxRedirects = opts.maxRedirects ?? 5;
+  const timeout = opts.timeoutMs ?? 2e4;
+  const userAgent = opts.userAgent ?? DEFAULT_UA;
+  const accept = opts.accept ?? "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+  let current = url;
+  let redirects = 0;
+  for (; ; ) {
+    const res = await request(current, {
+      method: "GET",
+      headers: {
+        "user-agent": userAgent,
+        accept,
+        "accept-language": "en,*"
+      },
+      bodyTimeout: timeout,
+      headersTimeout: timeout
+    });
+    const status = res.statusCode;
+    const headers = normalizeHeaders(res.headers);
+    if (status >= 300 && status < 400 && headers.location && redirects < maxRedirects) {
+      redirects += 1;
+      current = new URL(headers.location, current).toString();
+      await res.body.dump();
+      continue;
+    }
+    const body = await res.body.text();
+    return { finalUrl: current, status, headers, body, redirectCount: redirects };
+  }
+}
+async function fetchText(url, opts = {}) {
+  try {
+    const res = await fetchStatic(url, opts);
+    if (res.status >= 200 && res.status < 300) return res.body;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+// src/fetcher/rendered.ts
+async function fetchRendered(url, opts = {}) {
+  let playwright;
+  try {
+    playwright = await import("playwright");
+  } catch {
+    throw new Error(
+      "Playwright is required for --render. Install with: npm i -D playwright && npx playwright install chromium"
+    );
+  }
+  const userAgent = opts.userAgent ?? DEFAULT_UA;
+  const timeout = opts.timeoutMs ?? 3e4;
+  const browser = await playwright.chromium.launch({ headless: true });
+  try {
+    const ctx = await browser.newContext({ userAgent });
+    const page = await ctx.newPage();
+    const response = await page.goto(url, { waitUntil: "networkidle", timeout });
+    const html = await page.content();
+    const finalUrl = page.url();
+    const status = response?.status() ?? 200;
+    const headers = response ? await response.allHeaders() : {};
+    return { finalUrl, html, status, headers };
+  } finally {
+    await browser.close();
+  }
+}
+
+// src/fetcher/robots.ts
+function parseRobots(raw) {
+  const groups = [];
+  const sitemaps = [];
+  let current = null;
+  const lines = raw.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/#.*$/, "").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 === "user-agent") {
+      if (!current || current.allow.length > 0 || current.disallow.length > 0) {
+        current = { userAgent: value, allow: [], disallow: [] };
+        groups.push(current);
+      } else {
+        current.userAgent = value;
+      }
+    } else if (field === "allow" && current) {
+      current.allow.push(value);
+    } else if (field === "disallow" && current) {
+      current.disallow.push(value);
+    } else if (field === "sitemap") {
+      sitemaps.push(value);
+    }
+  }
+  return { raw, groups, sitemaps };
+}
+function matchGroup(robots, userAgent) {
+  const lower = userAgent.toLowerCase();
+  const exact = robots.groups.find((g) => g.userAgent.toLowerCase() === lower);
+  if (exact) return exact;
+  const wildcard = robots.groups.find((g) => g.userAgent === "*");
+  return wildcard ?? null;
+}
+function isPathAllowed(group, path) {
+  if (!group) return true;
+  const matches = (pattern) => {
+    if (pattern === "") return -1;
+    if (path.startsWith(pattern)) return pattern.length;
+    return -1;
+  };
+  let bestAllow = -1;
+  let bestDisallow = -1;
+  for (const p of group.allow) bestAllow = Math.max(bestAllow, matches(p));
+  for (const p of group.disallow) bestDisallow = Math.max(bestDisallow, matches(p));
+  if (bestDisallow === -1) return true;
+  return bestAllow >= bestDisallow;
+}
+
+// src/fetcher/llms-txt.ts
+var LINK_RE = /^\s*-\s*\[([^\]]+)\]\(([^)]+)\)\s*(?::\s*(.+))?\s*$/;
+function parseLlmsTxt(raw) {
+  const lines = raw.split(/\r?\n/);
+  let title = null;
+  let summary = null;
+  const sections = [];
+  let currentSection = null;
+  const summaryParts = [];
+  let inSummaryPhase = false;
+  for (const line of lines) {
+    if (/^#\s+/.test(line) && title === null) {
+      title = line.replace(/^#\s+/, "").trim();
+      inSummaryPhase = true;
+      continue;
+    }
+    if (/^##\s+/.test(line)) {
+      if (inSummaryPhase && summaryParts.length > 0) {
+        summary = summaryParts.join(" ").trim();
+      }
+      inSummaryPhase = false;
+      currentSection = { title: line.replace(/^##\s+/, "").trim(), links: [] };
+      sections.push(currentSection);
+      continue;
+    }
+    if (inSummaryPhase) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith(">")) {
+        summaryParts.push(trimmed.replace(/^>\s*/, ""));
+      } else if (trimmed.length > 0) {
+        summaryParts.push(trimmed);
+      }
+      continue;
+    }
+    if (currentSection) {
+      const m = LINK_RE.exec(line);
+      if (m) {
+        const link = { title: m[1].trim(), url: m[2].trim() };
+        if (m[3]) link.description = m[3].trim();
+        currentSection.links.push(link);
+      }
+    }
+  }
+  if (inSummaryPhase && summary === null && summaryParts.length > 0) {
+    summary = summaryParts.join(" ").trim();
+  }
+  return { raw, title, summary, sections };
+}
+function isLlmsTxtWellFormed(parsed) {
+  if (!parsed.title) return { ok: false, reason: "Missing H1 project title" };
+  if (parsed.sections.length === 0) return { ok: false, reason: "No H2 sections found" };
+  const totalLinks = parsed.sections.reduce((n, s) => n + s.links.length, 0);
+  if (totalLinks === 0) return { ok: false, reason: "No link items found under any section" };
+  return { ok: true };
+}
+
+// src/fetcher/sitemap.ts
+var LOC_RE = /<loc>\s*([^<\s]+)\s*<\/loc>/gi;
+var LASTMOD_RE = /<lastmod>\s*([^<\s]+)\s*<\/lastmod>/i;
+function parseSitemap(xml) {
+  const urls = [];
+  let match;
+  const re = new RegExp(LOC_RE.source, LOC_RE.flags);
+  while ((match = re.exec(xml)) !== null) {
+    const url = match[1];
+    if (url) urls.push(url);
+  }
+  const lastmodMatch = LASTMOD_RE.exec(xml);
+  const summary = { urls };
+  if (lastmodMatch?.[1]) summary.lastmod = lastmodMatch[1];
+  return summary;
+}
+
+// src/context.ts
+function extractJsonLd($) {
+  const blocks = [];
+  $('script[type="application/ld+json"]').each((_i, el) => {
+    const txt = $(el).contents().text().trim();
+    if (!txt) return;
+    try {
+      const parsed = JSON.parse(txt);
+      if (Array.isArray(parsed)) blocks.push(...parsed);
+      else blocks.push(parsed);
+    } catch {
+      blocks.push({ __parseError: true, raw: txt.slice(0, 200) });
+    }
+  });
+  return blocks;
+}
+function detectSpa($) {
+  const bodyText = $("body").clone().find("script, style, noscript").remove().end().text().replace(/\s+/g, " ").trim();
+  if (bodyText.length >= 500) return false;
+  const roots = $("#__next, #root, #app, [data-reactroot], [ng-app], [data-server-rendered]");
+  return roots.length > 0;
+}
+async function buildContext(url, opts = {}) {
+  const warnings = [];
+  let finalUrl;
+  let html;
+  let headers;
+  let status;
+  let renderMode;
+  if (opts.render) {
+    const page = await fetchRendered(url, opts);
+    finalUrl = page.finalUrl;
+    html = page.html;
+    headers = page.headers;
+    status = page.status;
+    renderMode = "rendered";
+  } else {
+    const page = await fetchStatic(url, opts);
+    finalUrl = page.finalUrl;
+    html = page.body;
+    headers = page.headers;
+    status = page.status;
+    renderMode = "static";
+  }
+  const $ = cheerioLoad(html);
+  const origin = new URL(finalUrl).origin;
+  if (renderMode === "static" && detectSpa($)) {
+    warnings.push(
+      "Site appears to be JS-rendered (sparse body + SPA root element). Re-run with --render for accurate results."
+    );
+  }
+  const [robotsRaw, llmsRaw] = await Promise.all([
+    fetchText(`${origin}/robots.txt`, opts),
+    fetchText(`${origin}/llms.txt`, opts)
+  ]);
+  let sitemapUrl = null;
+  const robots = robotsRaw ? parseRobots(robotsRaw) : null;
+  if (robots && robots.sitemaps.length > 0) sitemapUrl = robots.sitemaps[0] ?? null;
+  if (!sitemapUrl) sitemapUrl = `${origin}/sitemap.xml`;
+  const sitemapRaw = await fetchText(sitemapUrl, opts);
+  const sitemap = sitemapRaw ? parseSitemap(sitemapRaw) : null;
+  return {
+    url,
+    finalUrl,
+    html,
+    $,
+    headers,
+    status,
+    robots,
+    llmsTxt: llmsRaw ? parseLlmsTxt(llmsRaw) : null,
+    sitemap,
+    jsonLd: extractJsonLd($),
+    renderMode,
+    fetchedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    warnings
+  };
+}
+
+// src/types.ts
+function defineRule(rule) {
+  return rule;
+}
+var CATEGORY_WEIGHTS = {
+  crawler: 25,
+  "structured-data": 30,
+  citation: 25,
+  content: 20
+};
+
+// src/engine.ts
+var VERSION = "0.1.0";
+async function runRules(ctx, rules, opts = {}) {
+  const onlySet = opts.only ? new Set(opts.only) : null;
+  const catSet = opts.categories ? new Set(opts.categories) : null;
+  const buckets = {
+    crawler: { score: 0, weight: CATEGORY_WEIGHTS.crawler, results: [] },
+    "structured-data": { score: 0, weight: CATEGORY_WEIGHTS["structured-data"], results: [] },
+    citation: { score: 0, weight: CATEGORY_WEIGHTS.citation, results: [] },
+    content: { score: 0, weight: CATEGORY_WEIGHTS.content, results: [] }
+  };
+  for (const rule of rules) {
+    if (onlySet && !onlySet.has(rule.id)) continue;
+    if (catSet && !catSet.has(rule.category)) continue;
+    let result;
+    try {
+      result = await rule.run(ctx);
+    } catch (err) {
+      result = {
+        status: "skip",
+        score: 0,
+        rationale: `Rule crashed: ${err instanceof Error ? err.message : String(err)}`
+      };
+    }
+    buckets[rule.category].results.push({
+      id: rule.id,
+      title: rule.title,
+      weight: rule.weight,
+      ...result
+    });
+  }
+  for (const cat of Object.keys(buckets)) {
+    const b = buckets[cat];
+    let weighted = 0;
+    let totalWeight = 0;
+    for (const r of b.results) {
+      if (r.status === "skip") continue;
+      weighted += r.score * r.weight;
+      totalWeight += r.weight;
+    }
+    b.score = totalWeight === 0 ? 0 : Math.round(weighted / totalWeight * 100);
+  }
+  let overallWeighted = 0;
+  let overallWeight = 0;
+  for (const cat of Object.keys(buckets)) {
+    const b = buckets[cat];
+    if (b.results.length === 0) continue;
+    overallWeighted += b.score * b.weight;
+    overallWeight += b.weight;
+  }
+  const overall = overallWeight === 0 ? 0 : Math.round(overallWeighted / overallWeight);
+  return {
+    url: ctx.url,
+    finalUrl: ctx.finalUrl,
+    fetchedAt: ctx.fetchedAt,
+    renderMode: ctx.renderMode,
+    overall,
+    categories: buckets,
+    warnings: [...ctx.warnings],
+    version: VERSION
+  };
+}
+
+// src/rules/crawler/https.ts
+var httpsRule = defineRule({
+  id: "crawler.https",
+  category: "crawler",
+  weight: 2,
+  title: "Site is served over HTTPS",
+  description: "AI crawlers treat HTTPS pages as more trustworthy and some skip plain HTTP entirely.",
+  run(ctx) {
+    const isHttps = ctx.finalUrl.startsWith("https://");
+    return isHttps ? { status: "pass", score: 1, rationale: "Final URL uses HTTPS." } : {
+      status: "fail",
+      score: 0,
+      rationale: "Final URL does not use HTTPS. Redirect HTTP \u2192 HTTPS site-wide.",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/crawler/robots-reachable.ts
+var robotsReachableRule = defineRule({
+  id: "crawler.robots-reachable",
+  category: "crawler",
+  weight: 2,
+  title: "robots.txt is reachable",
+  description: "A reachable robots.txt lets crawlers confirm their permissions; missing file is treated as allow-all but blocks explicit signalling.",
+  run(ctx) {
+    if (ctx.robots) {
+      return { status: "pass", score: 1, rationale: "robots.txt returned successfully." };
+    }
+    return {
+      status: "warn",
+      score: 0.3,
+      rationale: "robots.txt is missing. Add one even if empty to explicitly signal crawl policy.",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/crawler/robots-ai-allow.ts
+var AI_BOTS = [
+  "GPTBot",
+  "Google-Extended",
+  "ClaudeBot",
+  "PerplexityBot",
+  "CCBot",
+  "Amazonbot",
+  "anthropic-ai"
+];
+var robotsAiAllowRule = defineRule({
+  id: "crawler.robots-ai-allow",
+  category: "crawler",
+  weight: 5,
+  title: "AI crawlers are allowed",
+  description: "Major AI search crawlers (GPTBot, Google-Extended, ClaudeBot, PerplexityBot, CCBot, Amazonbot) must be allowed to index the homepage.",
+  run(ctx) {
+    if (!ctx.robots) {
+      return {
+        status: "warn",
+        score: 0.5,
+        rationale: "robots.txt missing; AI crawlers default to allow, but explicit allow is recommended."
+      };
+    }
+    const path = new URL(ctx.finalUrl).pathname || "/";
+    const blocked = [];
+    const mentioned = [];
+    for (const bot of AI_BOTS) {
+      const group = matchGroup(ctx.robots, bot);
+      if (group && group.userAgent.toLowerCase() === bot.toLowerCase()) {
+        mentioned.push(bot);
+      }
+      if (!isPathAllowed(group, path)) blocked.push(bot);
+    }
+    if (blocked.length > 0) {
+      return {
+        status: "fail",
+        score: 0,
+        rationale: `Blocked: ${blocked.join(", ")}. Remove the Disallow or add an explicit Allow for these user-agents.`,
+        evidence: { blocked, mentioned },
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+      };
+    }
+    if (mentioned.length === 0) {
+      return {
+        status: "warn",
+        score: 0.6,
+        rationale: "No AI crawler is explicitly mentioned. Consider adding explicit Allow rules to remove ambiguity."
+      };
+    }
+    return {
+      status: "pass",
+      score: 1,
+      rationale: `All AI crawlers can reach the page; ${mentioned.length} explicitly listed.`,
+      evidence: { mentioned }
+    };
+  }
+});
+
+// src/rules/crawler/llms-txt-present.ts
+var llmsTxtPresentRule = defineRule({
+  id: "crawler.llms-txt-present",
+  category: "crawler",
+  weight: 4,
+  title: "llms.txt is present",
+  description: "An /llms.txt file at the site root gives AI assistants a curated map of the most citation-worthy pages.",
+  run(ctx) {
+    if (ctx.llmsTxt) {
+      return { status: "pass", score: 1, rationale: "llms.txt found at site root." };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No /llms.txt found. Add one to curate the pages AI assistants should read.",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/crawler/llms-txt-wellformed.ts
+var llmsTxtWellformedRule = defineRule({
+  id: "crawler.llms-txt-wellformed",
+  category: "crawler",
+  weight: 3,
+  title: "llms.txt follows the spec",
+  description: "Must start with an H1 project title, then a brief summary, then at least one H2 section containing link items.",
+  run(ctx) {
+    if (!ctx.llmsTxt) {
+      return { status: "skip", score: 0, rationale: "No llms.txt to validate." };
+    }
+    const check = isLlmsTxtWellFormed(ctx.llmsTxt);
+    if (check.ok) {
+      const totalLinks = ctx.llmsTxt.sections.reduce((n, s) => n + s.links.length, 0);
+      return {
+        status: "pass",
+        score: 1,
+        rationale: `Well-formed with ${ctx.llmsTxt.sections.length} section(s) and ${totalLinks} link(s).`
+      };
+    }
+    return {
+      status: "warn",
+      score: 0.3,
+      rationale: `llms.txt does not fully match the spec: ${check.reason}.`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/crawler/sitemap-present.ts
+var sitemapPresentRule = defineRule({
+  id: "crawler.sitemap-present",
+  category: "crawler",
+  weight: 4,
+  title: "sitemap.xml is present",
+  description: "A sitemap helps AI crawlers discover and prioritise pages; many crawlers short-circuit discovery without one.",
+  run(ctx) {
+    if (ctx.sitemap && ctx.sitemap.urls.length > 0) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: `Sitemap found with ${ctx.sitemap.urls.length} URL(s).`
+      };
+    }
+    return {
+      status: "warn",
+      score: 0.2,
+      rationale: "No sitemap.xml found (checked /sitemap.xml and Sitemap: directive in robots.txt).",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/crawler/index.ts
+var crawlerRules = [
+  httpsRule,
+  robotsReachableRule,
+  robotsAiAllowRule,
+  llmsTxtPresentRule,
+  llmsTxtWellformedRule,
+  sitemapPresentRule
+];
+
+// src/rules/structured-data/jsonld-present.ts
+var jsonLdPresentRule = defineRule({
+  id: "sd.jsonld-present",
+  category: "structured-data",
+  weight: 5,
+  title: "JSON-LD structured data is present",
+  description: 'At least one <script type="application/ld+json"> block is the primary way AI engines map your page to an entity.',
+  run(ctx) {
+    if (ctx.jsonLd.length > 0) {
+      return { status: "pass", score: 1, rationale: `Found ${ctx.jsonLd.length} JSON-LD block(s).` };
+    }
+    return {
+      status: "fail",
+      score: 0,
+      rationale: "No JSON-LD blocks found. Add schema.org structured data.",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/util.ts
+var KNOWN_SCHEMA_TYPES = [
+  "Article",
+  "NewsArticle",
+  "BlogPosting",
+  "FAQPage",
+  "HowTo",
+  "Organization",
+  "Person",
+  "BreadcrumbList",
+  "Product",
+  "WebSite",
+  "WebPage"
+];
+var REQUIRED_FIELDS = {
+  Article: ["headline", "author", "datePublished"],
+  NewsArticle: ["headline", "author", "datePublished"],
+  BlogPosting: ["headline", "author", "datePublished"],
+  FAQPage: ["mainEntity"],
+  HowTo: ["name", "step"],
+  Product: ["name", "offers"],
+  Organization: ["name"],
+  Person: ["name"],
+  BreadcrumbList: ["itemListElement"]
+};
+function getTypes(node) {
+  if (!node || typeof node !== "object") return [];
+  const t = node["@type"];
+  if (typeof t === "string") return [t];
+  if (Array.isArray(t)) return t.filter((x) => typeof x === "string");
+  return [];
+}
+function flattenJsonLd(blocks) {
+  const out = [];
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    out.push(node);
+    const graph = node["@graph"];
+    if (Array.isArray(graph)) for (const item of graph) visit(item);
+  };
+  for (const b of blocks) visit(b);
+  return out;
+}
+function hasParseError(blocks) {
+  return blocks.some((b) => b && typeof b === "object" && b.__parseError);
+}
+function hasField(node, field) {
+  if (!node || typeof node !== "object") return false;
+  const v = node[field];
+  if (v == null) return false;
+  if (typeof v === "string") return v.trim().length > 0;
+  if (Array.isArray(v)) return v.length > 0;
+  return true;
+}
+
+// src/rules/structured-data/jsonld-valid-json.ts
+var jsonLdValidJsonRule = defineRule({
+  id: "sd.jsonld-valid-json",
+  category: "structured-data",
+  weight: 3,
+  title: "JSON-LD blocks parse as valid JSON",
+  description: "Malformed JSON in an ld+json block is silently ignored by most consumers \u2014 a costly silent failure.",
+  run(ctx) {
+    if (ctx.jsonLd.length === 0) {
+      return { status: "skip", score: 0, rationale: "No JSON-LD to validate." };
+    }
+    if (hasParseError(ctx.jsonLd)) {
+      return {
+        status: "fail",
+        score: 0,
+        rationale: "One or more JSON-LD blocks failed to parse.",
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+      };
+    }
+    return { status: "pass", score: 1, rationale: "All JSON-LD blocks parse cleanly." };
+  }
+});
+
+// src/rules/structured-data/schema-type-recognized.ts
+var schemaTypeRecognizedRule = defineRule({
+  id: "sd.schema-type-recognized",
+  category: "structured-data",
+  weight: 4,
+  title: "Schema.org @type is a recognised kind",
+  description: "AI engines match pages against well-known types (Article, Product, FAQPage...). Obscure types weaken the signal.",
+  run(ctx) {
+    if (ctx.jsonLd.length === 0) {
+      return { status: "skip", score: 0, rationale: "No JSON-LD to analyse." };
+    }
+    const nodes = flattenJsonLd(ctx.jsonLd);
+    const recognized = /* @__PURE__ */ new Set();
+    const seenTypes = /* @__PURE__ */ new Set();
+    for (const node of nodes) {
+      for (const t of getTypes(node)) {
+        seenTypes.add(t);
+        if (KNOWN_SCHEMA_TYPES.includes(t)) recognized.add(t);
+      }
+    }
+    if (recognized.size > 0) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: `Recognised: ${[...recognized].join(", ")}.`,
+        evidence: { recognized: [...recognized], all: [...seenTypes] }
+      };
+    }
+    return {
+      status: "warn",
+      score: 0.3,
+      rationale: `No recognised schema.org types. Saw: ${[...seenTypes].join(", ") || "(none)"}.`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/structured-data/required-fields.ts
+var requiredFieldsRule = defineRule({
+  id: "sd.required-fields",
+  category: "structured-data",
+  weight: 6,
+  title: "Required fields for recognised types are set",
+  description: "Article needs headline/author/datePublished, FAQPage needs mainEntity, Product needs offers, etc.",
+  run(ctx) {
+    if (ctx.jsonLd.length === 0) {
+      return { status: "skip", score: 0, rationale: "No JSON-LD to analyse." };
+    }
+    const nodes = flattenJsonLd(ctx.jsonLd);
+    const missing = [];
+    const checked = [];
+    for (const node of nodes) {
+      for (const t of getTypes(node)) {
+        const required = REQUIRED_FIELDS[t];
+        if (!required) continue;
+        checked.push(t);
+        for (const f of required) {
+          if (!hasField(node, f)) missing.push({ type: t, field: f });
+        }
+      }
+    }
+    if (checked.length === 0) {
+      return {
+        status: "skip",
+        score: 0,
+        rationale: "No types with known required fields were found."
+      };
+    }
+    if (missing.length === 0) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: `Required fields set on ${checked.length} node(s).`
+      };
+    }
+    const msg = missing.map((m) => `${m.type}.${m.field}`).join(", ");
+    return {
+      status: "fail",
+      score: Math.max(0, 1 - missing.length / (checked.length * 2)),
+      rationale: `Missing required fields: ${msg}.`,
+      evidence: missing,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/structured-data/microdata-fallback.ts
+var microdataFallbackRule = defineRule({
+  id: "sd.microdata-fallback",
+  category: "structured-data",
+  weight: 2,
+  title: "Microdata or RDFa fallback when JSON-LD is missing",
+  description: "If JSON-LD is absent, inline microdata (itemscope/itemtype) or RDFa still gives some structured signal.",
+  run(ctx) {
+    if (ctx.jsonLd.length > 0) {
+      return { status: "skip", score: 0, rationale: "JSON-LD is present; fallback not needed." };
+    }
+    const microdata = ctx.$("[itemscope][itemtype]").length;
+    const rdfa = ctx.$("[typeof][vocab], [typeof][property]").length;
+    if (microdata > 0 || rdfa > 0) {
+      return {
+        status: "pass",
+        score: 1,
+        rationale: `Found ${microdata} microdata and ${rdfa} RDFa nodes.`
+      };
+    }
+    return {
+      status: "fail",
+      score: 0,
+      rationale: "No structured data at all (no JSON-LD, no microdata, no RDFa).",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/structured-data/no-duplicate-types.ts
+var UNIQUE_TYPES = /* @__PURE__ */ new Set(["Article", "NewsArticle", "BlogPosting", "Product", "Organization"]);
+var noDuplicateTypesRule = defineRule({
+  id: "sd.no-duplicate-types",
+  category: "structured-data",
+  weight: 2,
+  title: "No conflicting duplicate @types",
+  description: "Multiple competing entities of the same primary type (e.g. two Articles) confuse the engine about which one represents the page.",
+  run(ctx) {
+    if (ctx.jsonLd.length === 0) {
+      return { status: "skip", score: 0, rationale: "No JSON-LD to analyse." };
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (const node of flattenJsonLd(ctx.jsonLd)) {
+      for (const t of getTypes(node)) {
+        if (UNIQUE_TYPES.has(t)) counts.set(t, (counts.get(t) ?? 0) + 1);
+      }
+    }
+    const dupes = [...counts.entries()].filter(([, n]) => n > 1);
+    if (dupes.length === 0) {
+      return { status: "pass", score: 1, rationale: "No duplicate primary types." };
+    }
+    return {
+      status: "warn",
+      score: 0.4,
+      rationale: `Duplicate primary types: ${dupes.map(([t, n]) => `${t}\xD7${n}`).join(", ")}.`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/structured-data/index.ts
+var structuredDataRules = [
+  jsonLdPresentRule,
+  jsonLdValidJsonRule,
+  schemaTypeRecognizedRule,
+  requiredFieldsRule,
+  microdataFallbackRule,
+  noDuplicateTypesRule
+];
+
+// src/rules/citation/title.ts
+var titleRule = defineRule({
+  id: "cit.title",
+  category: "citation",
+  weight: 2,
+  title: "<title> is set with a reasonable length",
+  description: "The document title is the single most-cited piece of text and should be 10\u201370 characters.",
+  run(ctx) {
+    const title = ctx.$("head > title").first().text().trim();
+    if (!title) {
+      return {
+        status: "fail",
+        score: 0,
+        rationale: "Page has no <title>.",
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+      };
+    }
+    if (title.length < 10) {
+      return {
+        status: "warn",
+        score: 0.4,
+        rationale: `Title is only ${title.length} chars; consider a more descriptive one.`
+      };
+    }
+    if (title.length > 70) {
+      return {
+        status: "warn",
+        score: 0.6,
+        rationale: `Title is ${title.length} chars; search UIs commonly truncate after ~70.`
+      };
+    }
+    return { status: "pass", score: 1, rationale: `Title length ${title.length} is within range.` };
+  }
+});
+
+// src/rules/citation/meta-description.ts
+var metaDescriptionRule = defineRule({
+  id: "cit.meta-description",
+  category: "citation",
+  weight: 2,
+  title: "meta description is set (50\u2013160 chars)",
+  description: "AI snippets often quote the meta description verbatim; aim for 50\u2013160 chars.",
+  run(ctx) {
+    const desc = ctx.$('head meta[name="description"]').attr("content")?.trim() ?? "";
+    if (!desc) {
+      return {
+        status: "warn",
+        score: 0,
+        rationale: "No meta description set.",
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+      };
+    }
+    if (desc.length < 50) {
+      return { status: "warn", score: 0.5, rationale: `Only ${desc.length} chars; aim for 50+.` };
+    }
+    if (desc.length > 160) {
+      return { status: "warn", score: 0.7, rationale: `${desc.length} chars; may be truncated after 160.` };
+    }
+    return { status: "pass", score: 1, rationale: `Description length ${desc.length} is within range.` };
+  }
+});
+
+// src/rules/citation/canonical.ts
+var canonicalRule = defineRule({
+  id: "cit.canonical",
+  category: "citation",
+  weight: 3,
+  title: "Canonical URL is declared",
+  description: 'rel="canonical" tells crawlers which URL is the source of truth, preventing duplicate-citation confusion.',
+  run(ctx) {
+    const href = ctx.$('head link[rel="canonical"]').attr("href")?.trim();
+    if (!href) {
+      return {
+        status: "warn",
+        score: 0,
+        rationale: 'No <link rel="canonical"> found.',
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+      };
+    }
+    try {
+      const abs = new URL(href, ctx.finalUrl).toString();
+      return { status: "pass", score: 1, rationale: `Canonical URL: ${abs}.` };
+    } catch {
+      return { status: "fail", score: 0, rationale: `Canonical href is not a valid URL: ${href}` };
+    }
+  }
+});
+
+// src/rules/citation/og-tags.ts
+var REQUIRED = ["og:title", "og:type", "og:url", "og:image"];
+var ogTagsRule = defineRule({
+  id: "cit.og-tags",
+  category: "citation",
+  weight: 3,
+  title: "Open Graph tags are set",
+  description: "og:title/type/url/image power rich previews on AI chat, social, and messaging.",
+  run(ctx) {
+    const missing = [];
+    for (const prop of REQUIRED) {
+      const val = ctx.$(`head meta[property="${prop}"]`).attr("content")?.trim();
+      if (!val) missing.push(prop);
+    }
+    if (missing.length === 0) {
+      return { status: "pass", score: 1, rationale: "All required OG tags present." };
+    }
+    const ratio = 1 - missing.length / REQUIRED.length;
+    return {
+      status: missing.length === REQUIRED.length ? "fail" : "warn",
+      score: ratio,
+      rationale: `Missing: ${missing.join(", ")}.`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/citation/twitter-card.ts
+var twitterCardRule = defineRule({
+  id: "cit.twitter-card",
+  category: "citation",
+  weight: 2,
+  title: "Twitter Card metadata is set",
+  description: "twitter:card + twitter:title give better previews on X/Twitter and some AI surfaces that reuse the tags.",
+  run(ctx) {
+    const card = ctx.$('head meta[name="twitter:card"]').attr("content")?.trim();
+    const title = ctx.$('head meta[name="twitter:title"]').attr("content")?.trim();
+    if (card && title) {
+      return { status: "pass", score: 1, rationale: `Card type: ${card}.` };
+    }
+    if (card || title) {
+      return { status: "warn", score: 0.5, rationale: "Partial twitter:* metadata; add the missing tag." };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No twitter:card metadata.",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/citation/lang-attr.ts
+var langAttrRule = defineRule({
+  id: "cit.lang-attr",
+  category: "citation",
+  weight: 2,
+  title: "<html lang> is set",
+  description: "A lang attribute helps AI engines route the page to the right-language search surface (and helps screen readers).",
+  run(ctx) {
+    const lang = ctx.$("html").attr("lang")?.trim();
+    if (!lang) {
+      return {
+        status: "warn",
+        score: 0,
+        rationale: "No lang attribute on <html>.",
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+      };
+    }
+    return { status: "pass", score: 1, rationale: `lang="${lang}".` };
+  }
+});
+
+// src/rules/citation/author-visible.ts
+var authorVisibleRule = defineRule({
+  id: "cit.author-visible",
+  category: "citation",
+  weight: 4,
+  title: "Author is declared",
+  description: "AI engines prefer citing content with an identifiable author; expose one via JSON-LD, meta[name=author], rel=author, or a .author class.",
+  run(ctx) {
+    for (const node of flattenJsonLd(ctx.jsonLd)) {
+      if (hasField(node, "author")) {
+        return { status: "pass", score: 1, rationale: "Author found in JSON-LD." };
+      }
+    }
+    const metaAuthor = ctx.$('head meta[name="author"]').attr("content")?.trim();
+    if (metaAuthor) return { status: "pass", score: 1, rationale: `meta[name=author] = "${metaAuthor}".` };
+    if (ctx.$('[rel="author"]').length > 0) {
+      return { status: "pass", score: 1, rationale: 'rel="author" link found.' };
+    }
+    if (ctx.$('.author, [class*="author"], [itemprop="author"]').length > 0) {
+      return { status: "pass", score: 0.8, rationale: "Author-ish DOM selector found (weaker signal)." };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No author signal found (JSON-LD, meta, rel, or .author).",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/citation/dates.ts
+var datesRule = defineRule({
+  id: "cit.dates",
+  category: "citation",
+  weight: 5,
+  title: "Publish / modified date is present",
+  description: "AI engines rank recent pages higher; expose datePublished via JSON-LD, <time datetime>, or article:published_time meta.",
+  run(ctx) {
+    for (const node of flattenJsonLd(ctx.jsonLd)) {
+      if (hasField(node, "datePublished")) {
+        return { status: "pass", score: 1, rationale: "datePublished found in JSON-LD." };
+      }
+    }
+    const articleTime = ctx.$('head meta[property="article:published_time"]').attr("content")?.trim();
+    if (articleTime) {
+      return { status: "pass", score: 1, rationale: `article:published_time = ${articleTime}.` };
+    }
+    const timeEl = ctx.$("time[datetime]").first().attr("datetime")?.trim();
+    if (timeEl) {
+      return { status: "pass", score: 0.8, rationale: `<time datetime="${timeEl}"> found.` };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No publish date found (JSON-LD, meta article:published_time, or <time datetime>).",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/citation/index.ts
+var citationRules = [
+  titleRule,
+  metaDescriptionRule,
+  canonicalRule,
+  ogTagsRule,
+  twitterCardRule,
+  langAttrRule,
+  authorVisibleRule,
+  datesRule
+];
+
+// src/rules/content/single-h1.ts
+var singleH1Rule = defineRule({
+  id: "cnt.single-h1",
+  category: "content",
+  weight: 3,
+  title: "Exactly one <h1>",
+  description: "A single H1 tells AI engines the primary topic of the page without ambiguity.",
+  run(ctx) {
+    const n = ctx.$("h1").length;
+    if (n === 1) return { status: "pass", score: 1, rationale: "Exactly one <h1>." };
+    if (n === 0) {
+      return {
+        status: "fail",
+        score: 0,
+        rationale: "No <h1> on the page.",
+        fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules/cnt.single-h1.md"
+      };
+    }
+    return {
+      status: "warn",
+      score: Math.max(0.3, 1 / n),
+      rationale: `Found ${n} <h1> tags; prefer one primary heading.`
+    };
+  }
+});
+
+// src/rules/content/heading-hierarchy.ts
+var headingHierarchyRule = defineRule({
+  id: "cnt.heading-hierarchy",
+  category: "content",
+  weight: 3,
+  title: "Heading levels do not skip",
+  description: "Going from H2 directly to H4 breaks the outline AI engines use to segment content.",
+  run(ctx) {
+    const levels = [];
+    ctx.$("h1, h2, h3, h4, h5, h6").each((_i, el) => {
+      const name = el.tagName?.toLowerCase() ?? "h1";
+      const m = /^h([1-6])$/.exec(name);
+      if (m?.[1]) levels.push(parseInt(m[1], 10));
+    });
+    if (levels.length === 0) {
+      return { status: "skip", score: 0, rationale: "No headings found." };
+    }
+    const skips = [];
+    for (let i = 1; i < levels.length; i++) {
+      const prev = levels[i - 1];
+      const curr = levels[i];
+      if (curr > prev + 1) skips.push({ from: prev, to: curr });
+    }
+    if (skips.length === 0) {
+      return { status: "pass", score: 1, rationale: "No heading-level skips." };
+    }
+    return {
+      status: "warn",
+      score: Math.max(0.3, 1 - skips.length / levels.length),
+      rationale: `${skips.length} heading skip(s) detected (e.g. h${skips[0].from}\u2192h${skips[0].to}).`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/content/image-alt.ts
+var imageAltRule = defineRule({
+  id: "cnt.image-alt",
+  category: "content",
+  weight: 3,
+  title: "\u226580% of <img> have alt text",
+  description: "Alt text gives AI engines a textual anchor for visual content and improves accessibility.",
+  run(ctx) {
+    const imgs = ctx.$("img");
+    const total = imgs.length;
+    if (total === 0) return { status: "skip", score: 0, rationale: "No <img> on the page." };
+    let withAlt = 0;
+    imgs.each((_i, el) => {
+      const alt = ctx.$(el).attr("alt");
+      if (typeof alt === "string" && alt.trim().length > 0) withAlt += 1;
+    });
+    const ratio = withAlt / total;
+    if (ratio >= 0.8) {
+      return { status: "pass", score: 1, rationale: `${withAlt}/${total} images have alt (${Math.round(ratio * 100)}%).` };
+    }
+    return {
+      status: "warn",
+      score: ratio,
+      rationale: `Only ${withAlt}/${total} images have alt text (${Math.round(ratio * 100)}%). Aim for \u226580%.`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/content/tldr-or-faq.ts
+var tldrOrFaqRule = defineRule({
+  id: "cnt.tldr-or-faq",
+  category: "content",
+  weight: 5,
+  title: "TL;DR summary or FAQ block",
+  description: 'AI engines strongly prefer content with a quotable summary or FAQ \u2014 it makes the page "citation-ready".',
+  run(ctx) {
+    for (const node of flattenJsonLd(ctx.jsonLd)) {
+      if (getTypes(node).includes("FAQPage")) {
+        return { status: "pass", score: 1, rationale: "FAQPage schema present." };
+      }
+    }
+    const sel = [
+      'section[id*="tldr" i]',
+      'section[id*="summary" i]',
+      'section[id*="faq" i]',
+      ".tldr",
+      ".summary",
+      ".faq",
+      "[data-tldr]"
+    ].join(", ");
+    if (ctx.$(sel).length > 0) {
+      return { status: "pass", score: 0.85, rationale: "TL;DR / summary / FAQ region detected by selector." };
+    }
+    return {
+      status: "warn",
+      score: 0,
+      rationale: "No TL;DR / summary / FAQ found; add one to boost AI citation odds.",
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/content/word-count.ts
+var wordCountRule = defineRule({
+  id: "cnt.word-count",
+  category: "content",
+  weight: 2,
+  title: "Page has enough body text",
+  description: "Thin pages (under ~100 words) are rarely cited by AI engines. Aim for \u2265300 words of meaningful body copy.",
+  run(ctx) {
+    const $ = ctx.$;
+    const clone = $("body").clone();
+    clone.find("script, style, noscript, nav, header, footer, aside").remove();
+    const text = clone.text().replace(/\s+/g, " ").trim();
+    const words = text ? text.split(" ").length : 0;
+    if (words >= 300) return { status: "pass", score: 1, rationale: `${words} words of body text.` };
+    if (words >= 100) return { status: "warn", score: 0.5, rationale: `Only ${words} words; aim for 300+.` };
+    return {
+      status: "fail",
+      score: 0,
+      rationale: `Only ${words} words; too thin to be cited.`,
+      fixUrl: "https://github.com/BaRam-OSS/geo-checker/blob/main/docs/rules.md"
+    };
+  }
+});
+
+// src/rules/content/index.ts
+var contentRules = [
+  singleH1Rule,
+  headingHierarchyRule,
+  imageAltRule,
+  tldrOrFaqRule,
+  wordCountRule
+];
+
+// src/rules/index.ts
+var defaultRules = [
+  ...crawlerRules,
+  ...structuredDataRules,
+  ...citationRules,
+  ...contentRules
+];
+
+// src/index.ts
+async function audit(url, options = {}) {
+  const ctx = await buildContext(url, {
+    ...options.render ? { render: true } : {},
+    ...options.userAgent !== void 0 ? { userAgent: options.userAgent } : {},
+    ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {}
+  });
+  const rules = [...defaultRules, ...options.extraRules ?? []];
+  return runRules(ctx, rules, {
+    ...options.only ? { only: options.only } : {},
+    ...options.categories ? { categories: options.categories } : {}
+  });
+}
+
+// src/reporters/json.ts
+function toJson(report, pretty = true) {
+  return pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
+}
+
+// src/reporters/cli.ts
+import kleur from "kleur";
+import Table from "cli-table3";
+var CATEGORY_LABELS = {
+  crawler: "AI Crawler Access",
+  "structured-data": "Structured Data",
+  citation: "Citation Signals",
+  content: "Content Structure"
+};
+function colorScore(score) {
+  if (score >= 85) return kleur.green().bold(`${score}`);
+  if (score >= 60) return kleur.yellow().bold(`${score}`);
+  return kleur.red().bold(`${score}`);
+}
+function statusBadge(status) {
+  switch (status) {
+    case "pass":
+      return kleur.green("pass");
+    case "warn":
+      return kleur.yellow("warn");
+    case "fail":
+      return kleur.red("fail");
+    default:
+      return kleur.gray("skip");
+  }
+}
+function bar(score, width = 20) {
+  const filled = Math.round(score / 100 * width);
+  const empty = width - filled;
+  const color = score >= 85 ? kleur.green : score >= 60 ? kleur.yellow : kleur.red;
+  return color("\u2588".repeat(filled)) + kleur.gray("\u2591".repeat(empty));
+}
+function toCli(report) {
+  const lines = [];
+  lines.push("");
+  lines.push(
+    kleur.bold("geo-checker") + kleur.gray(" \xB7 ") + report.finalUrl + kleur.gray(`  (${report.renderMode})`)
+  );
+  lines.push(
+    kleur.gray("fetched ") + report.fetchedAt + kleur.gray("  \xB7  v") + report.version
+  );
+  lines.push("");
+  lines.push(kleur.bold("Overall ") + colorScore(report.overall) + kleur.gray(" / 100"));
+  lines.push("");
+  for (const w of report.warnings) {
+    lines.push(kleur.yellow("!  ") + w);
+  }
+  if (report.warnings.length > 0) lines.push("");
+  for (const cat of Object.keys(report.categories)) {
+    const b = report.categories[cat];
+    if (b.results.length === 0) continue;
+    lines.push(
+      `  ${kleur.bold(CATEGORY_LABELS[cat].padEnd(20))} ${bar(b.score)}  ${colorScore(b.score).padStart(3)}/100`
+    );
+    const table = new Table({
+      head: [kleur.gray("status"), kleur.gray("rule"), kleur.gray("note")],
+      colWidths: [7, 34, 70],
+      wordWrap: true,
+      style: { head: [], border: ["grey"] }
+    });
+    for (const r of b.results) {
+      table.push([statusBadge(r.status), r.id, r.rationale]);
+    }
+    lines.push(
+      table.toString().split("\n").map((l) => "    " + l).join("\n")
+    );
+    lines.push("");
+  }
+  const fixUrls = Object.values(report.categories).flatMap((c) => c.results).filter((r) => (r.status === "fail" || r.status === "warn") && r.fixUrl).map((r) => `  - ${r.id}: ${r.fixUrl}`);
+  if (fixUrls.length > 0) {
+    lines.push(kleur.bold("How to fix:"));
+    lines.push(...fixUrls);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/cli.ts
+var pkgVersion = "0.1.0";
+var VALID_CATEGORIES = ["crawler", "structured-data", "citation", "content"];
+function parseCategories(raw) {
+  if (!raw) return void 0;
+  const items = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const valid = items.filter((c) => VALID_CATEGORIES.includes(c));
+  const invalid = items.filter((c) => !VALID_CATEGORIES.includes(c));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown category: ${invalid.join(", ")}. Valid: ${VALID_CATEGORIES.join(", ")}.`);
+  }
+  return valid;
+}
+function parseOnly(raw) {
+  if (!raw) return void 0;
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function worstStatus(report) {
+  let worst = "pass";
+  const order = { pass: 0, skip: 0, warn: 1, fail: 2 };
+  for (const cat of Object.values(report.categories)) {
+    for (const r of cat.results) {
+      if (order[r.status] > order[worst]) worst = r.status;
+    }
+  }
+  return worst;
+}
+var cli = cac("geo-checker");
+cli.command("<url>", "Audit a URL for GEO (Generative Engine Optimization) readiness").option("--json", "Output a JSON report to stdout").option("--render", "Use a headless browser (requires optional playwright dependency)").option("--category <names>", "Run only the given categories (comma-separated)").option("--only <ids>", "Run only the given rule IDs (comma-separated)").option("--fail-on <level>", "Exit non-zero when a result is at or above this level (warn|fail)", {
+  default: "fail"
+}).option("--timeout <ms>", "Per-request timeout in milliseconds", { default: 2e4 }).action(async (url, flags) => {
+  const categories = parseCategories(flags.category);
+  const only = parseOnly(flags.only);
+  const timeoutMs = typeof flags.timeout === "string" ? parseInt(flags.timeout, 10) : flags.timeout;
+  const report = await audit(url, {
+    ...flags.render ? { render: true } : {},
+    ...categories ? { categories } : {},
+    ...only ? { only } : {},
+    ...typeof timeoutMs === "number" && !Number.isNaN(timeoutMs) ? { timeoutMs } : {}
+  });
+  if (flags.json) {
+    process.stdout.write(toJson(report) + "\n");
+  } else {
+    process.stdout.write(toCli(report) + "\n");
+  }
+  const worst = worstStatus(report);
+  const failOn = flags.failOn === "warn" ? "warn" : "fail";
+  if (failOn === "fail" && worst === "fail") process.exit(1);
+  if (failOn === "warn" && (worst === "warn" || worst === "fail")) process.exit(1);
+});
+cli.help();
+cli.version(pkgVersion);
+async function main() {
+  cli.parse(process.argv, { run: false });
+  await cli.runMatchedCommand();
+}
+main().catch((err) => {
+  console.error(kleur2.red("geo-checker crashed:"), err instanceof Error ? err.message : err);
+  process.exit(2);
+});
+//# sourceMappingURL=cli.js.map