geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/pdf-report.js

@@ -0,0 +1,205 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * PDF-ready HTML report generator.
+ * Generates a self-contained HTML file designed for browser Print-to-PDF.
+ * Zero external dependencies — uses only inline CSS.
+ */
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function scoreColor(score) {
+  if (score >= 80) return "#22c55e";
+  if (score >= 60) return "#eab308";
+  if (score >= 40) return "#f97316";
+  return "#ef4444";
+}
+
+function buildScoreGauge(score, label, maxScore = 100) {
+  const color = scoreColor(score);
+  const pct = Math.round((score / maxScore) * 100);
+  return `
+    <div class="gauge">
+      <div class="gauge-ring" style="background: conic-gradient(${color} ${pct * 3.6}deg, #e5e7eb ${pct * 3.6}deg)">
+        <div class="gauge-center">
+          <span class="gauge-score">${score}</span>
+          <span class="gauge-max">/ ${maxScore}</span>
+        </div>
+      </div>
+      <div class="gauge-label">${escapeHtml(label)}</div>
+    </div>`;
+}
+
+function buildCheckTable(checks) {
+  if (!checks || checks.length === 0) return "";
+  const rows = checks.map((c) => `
+    <tr>
+      <td>${c.passed ? "✅" : "❌"}</td>
+      <td>${escapeHtml(c.label || c.key)}</td>
+      <td>${c.pointsAwarded ?? (c.passed ? "pass" : "fail")}${c.maxPoints ? ` / ${c.maxPoints}` : ""}</td>
+    </tr>`).join("");
+
+  return `
+    <table>
+      <thead><tr><th></th><th>Check</th><th>Score</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table>`;
+}
+
+function buildIssueList(issues) {
+  if (!issues || issues.length === 0) return "<p>No issues found.</p>";
+  return `<ul>${issues.map((i) => `<li><strong>${escapeHtml(typeof i === "string" ? i : i.message || i.action || JSON.stringify(i))}</strong></li>`).join("")}</ul>`;
+}
+
+function buildSectionFromAudit(audit) {
+  const sections = [];
+
+  sections.push(`<h2>Summary</h2><p>${escapeHtml(audit.summary || "")}</p>`);
+
+  if (audit.checks) {
+    sections.push(`<h2>Score Breakdown</h2>${buildCheckTable(audit.checks)}`);
+  }
+
+  if (audit.areas) {
+    sections.push("<h2>Issue Areas</h2>");
+    for (const area of audit.areas) {
+      const sev = (area.severity || "").toLowerCase();
+      const severity = (sev === "高" || sev === "high") ? "🔴" : (sev === "中" || sev === "medium") ? "🟡" : "🟢";
+      sections.push(`
+        <div class="area-card">
+          <h3>${severity} ${escapeHtml(area.title)}</h3>
+          <p><strong>Owner:</strong> ${escapeHtml(area.owner)} | <strong>Status:</strong> ${escapeHtml(area.status)}</p>
+          <p>${escapeHtml(area.summary)}</p>
+        </div>`);
+    }
+  }
+
+  if (audit.actionPlan) {
+    sections.push("<h2>Action Plan</h2>");
+    sections.push(`<table>
+      <thead><tr><th>Priority</th><th>Owner</th><th>Area</th><th>Action</th></tr></thead>
+      <tbody>${audit.actionPlan.map((t) => `
+        <tr>
+          <td><span class="badge badge-${(t.priority || "P2").toLowerCase()}">${escapeHtml(t.priority || "P2")}</span></td>
+          <td>${escapeHtml(t.owner || "")}</td>
+          <td>${escapeHtml(t.area || "")}</td>
+          <td>${escapeHtml(t.action || "")}</td>
+        </tr>`).join("")}
+      </tbody></table>`);
+  }
+
+  if (audit.groups) {
+    if (audit.groups.blockers?.length > 0) {
+      sections.push(`<h2>Blockers</h2>${buildIssueList(audit.groups.blockers)}`);
+    }
+    if (audit.groups.highImpactFixes?.length > 0) {
+      sections.push(`<h2>High Impact Fixes</h2>${buildIssueList(audit.groups.highImpactFixes)}`);
+    }
+  }
+
+  if (audit.recommendations) {
+    sections.push(`<h2>Recommendations</h2>${buildIssueList(audit.recommendations)}`);
+  }
+
+  return sections.join("\n");
+}
+
+const CSS = `
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; color: #1f2937; line-height: 1.6; padding: 40px; max-width: 900px; margin: 0 auto; }
+  h1 { font-size: 28px; margin-bottom: 8px; color: #111827; }
+  h2 { font-size: 20px; margin: 32px 0 12px; color: #374151; border-bottom: 2px solid #e5e7eb; padding-bottom: 6px; }
+  h3 { font-size: 16px; margin: 16px 0 8px; color: #4b5563; }
+  p { margin: 8px 0; }
+  table { width: 100%; border-collapse: collapse; margin: 12px 0; font-size: 14px; }
+  th, td { border: 1px solid #e5e7eb; padding: 8px 12px; text-align: left; }
+  th { background: #f9fafb; font-weight: 600; }
+  tr:nth-child(even) { background: #f9fafb; }
+  ul { margin: 8px 0 8px 24px; }
+  li { margin: 4px 0; }
+  .header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 24px; }
+  .header-info { flex: 1; }
+  .meta { color: #6b7280; font-size: 14px; }
+  .gauges { display: flex; gap: 24px; flex-wrap: wrap; margin: 24px 0; }
+  .gauge { text-align: center; }
+  .gauge-ring { width: 120px; height: 120px; border-radius: 50%; display: flex; align-items: center; justify-content: center; }
+  .gauge-center { width: 90px; height: 90px; border-radius: 50%; background: white; display: flex; flex-direction: column; align-items: center; justify-content: center; }
+  .gauge-score { font-size: 28px; font-weight: 700; }
+  .gauge-max { font-size: 12px; color: #9ca3af; }
+  .gauge-label { margin-top: 8px; font-size: 13px; font-weight: 500; color: #6b7280; }
+  .area-card { background: #f9fafb; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; margin: 12px 0; }
+  .badge { padding: 2px 8px; border-radius: 4px; font-size: 12px; font-weight: 600; }
+  .badge-p0 { background: #fef2f2; color: #dc2626; }
+  .badge-p1 { background: #fff7ed; color: #ea580c; }
+  .badge-p2 { background: #fefce8; color: #ca8a04; }
+  .footer { margin-top: 48px; padding-top: 16px; border-top: 1px solid #e5e7eb; font-size: 12px; color: #9ca3af; }
+  @media print { body { padding: 20px; } .area-card { break-inside: avoid; } table { break-inside: avoid; } }
+`;
+
+export function generatePdfHtml(data, options = {}) {
+  const title = options.title || "GEO Audit Report";
+  const date = options.date || new Date().toISOString().split("T")[0];
+  const score = data.score ?? 0;
+  const maxScore = data.maxScore ?? 100;
+  const scoreLabel = data.scoreLabel || "";
+
+  const gauges = [buildScoreGauge(score, "GEO Score", maxScore)];
+
+  if (data.dimensions) {
+    for (const [key, dim] of Object.entries(data.dimensions)) {
+      if (dim.score !== undefined) {
+        gauges.push(buildScoreGauge(dim.score, key, 100));
+      }
+    }
+  }
+
+  const body = buildSectionFromAudit(data);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+  <style>${CSS}</style>
+</head>
+<body>
+  <div class="header">
+    <div class="header-info">
+      <h1>${escapeHtml(title)}</h1>
+      <p class="meta">Generated: ${escapeHtml(date)} | Source: ${escapeHtml(data.source || data.scanSummary?.root || "—")}</p>
+    </div>
+  </div>
+
+  <div class="gauges">${gauges.join("")}</div>
+
+  ${body}
+
+  <div class="footer">
+    Generated by geo-ai-search-optimization v2.2.0 — Open-source GEO toolkit for AI search optimization.
+    <br>Print this page to PDF for a polished report.
+  </div>
+</body>
+</html>`;
+}
+
+export async function writePdfReport(inputPath, outputPath, options = {}) {
+  const resolvedInput = path.resolve(inputPath);
+  const content = await fs.readFile(resolvedInput, "utf8");
+  const data = JSON.parse(content);
+
+  const html = generatePdfHtml(data, options);
+  const resolvedOutput = path.resolve(outputPath || inputPath.replace(/\.json$/, ".html"));
+
+  await fs.mkdir(path.dirname(resolvedOutput), { recursive: true });
+  await fs.writeFile(resolvedOutput, html, "utf8");
+
+  return { outputPath: resolvedOutput, title: options.title || "GEO Audit Report" };
+}

package/src/platform-ready.js

@@ -0,0 +1,238 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+function stripHtml(text) {
+  return text
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const PLATFORMS = {
+  chatgpt: {
+    name: "ChatGPT",
+    crawlers: ["GPTBot", "ChatGPT-User", "OAI-SearchBot"],
+    checks: [
+      { key: "llmsTxt", label: "llms.txt present", test: (ctx) => ctx.hasLlmsTxt },
+      { key: "jsonLd", label: "JSON-LD structured data", test: (ctx) => ctx.hasJsonLd },
+      { key: "answerFirst", label: "Answer-first opening paragraph", test: (ctx) => ctx.hasDirectAnswer },
+      { key: "crawlerAccess", label: "GPTBot not blocked in robots.txt", test: (ctx) => !ctx.blockedCrawlers.includes("GPTBot") },
+      { key: "metaDesc", label: "Meta description present", test: (ctx) => ctx.hasMetaDescription },
+      { key: "cleanHtml", label: "Clean semantic HTML", test: (ctx) => ctx.hasSemanticHtml }
+    ]
+  },
+  perplexity: {
+    name: "Perplexity",
+    crawlers: ["PerplexityBot"],
+    checks: [
+      { key: "citations", label: "Source links / citations", test: (ctx) => ctx.hasCitations },
+      { key: "factDensity", label: "High factual claim density", test: (ctx) => ctx.factDensity > 10 },
+      { key: "crawlerAccess", label: "PerplexityBot not blocked", test: (ctx) => !ctx.blockedCrawlers.includes("PerplexityBot") },
+      { key: "author", label: "Author attribution", test: (ctx) => ctx.hasAuthor },
+      { key: "freshness", label: "Content freshness signals", test: (ctx) => ctx.hasFreshness },
+      { key: "qaStructure", label: "Q&A structure", test: (ctx) => ctx.hasQaHeadings }
+    ]
+  },
+  gemini: {
+    name: "Google Gemini",
+    crawlers: ["Google-Extended", "Googlebot"],
+    checks: [
+      { key: "schemaOrg", label: "Schema.org markup", test: (ctx) => ctx.hasJsonLd },
+      { key: "entityClarity", label: "Clear entity identification", test: (ctx) => ctx.entityCount > 3 },
+      { key: "crawlerAccess", label: "Google-Extended not blocked", test: (ctx) => !ctx.blockedCrawlers.includes("Google-Extended") },
+      { key: "canonical", label: "Canonical URL", test: (ctx) => ctx.hasCanonical },
+      { key: "breadcrumb", label: "Breadcrumb markup", test: (ctx) => ctx.hasBreadcrumb },
+      { key: "sameAs", label: "sameAs links for entity resolution", test: (ctx) => ctx.hasSameAs }
+    ]
+  },
+  googleAio: {
+    name: "Google AI Overviews",
+    crawlers: ["Googlebot"],
+    checks: [
+      { key: "snippetReady", label: "Featured snippet-ready format", test: (ctx) => ctx.hasDirectAnswer },
+      { key: "listOrTable", label: "Lists or tables present", test: (ctx) => ctx.hasListOrTable },
+      { key: "faqSchema", label: "FAQ schema", test: (ctx) => ctx.hasFaqSchema },
+      { key: "howtoSchema", label: "HowTo schema", test: (ctx) => ctx.hasHowtoSchema },
+      { key: "heading", label: "Question-style headings", test: (ctx) => ctx.hasQaHeadings },
+      { key: "metaDesc", label: "Descriptive meta description", test: (ctx) => ctx.hasMetaDescription }
+    ]
+  },
+  bingCopilot: {
+    name: "Bing Copilot",
+    crawlers: ["Bingbot"],
+    checks: [
+      { key: "ogTags", label: "Open Graph meta tags", test: (ctx) => ctx.hasOgTags },
+      { key: "jsonLd", label: "JSON-LD structured data", test: (ctx) => ctx.hasJsonLd },
+      { key: "author", label: "Author and publisher info", test: (ctx) => ctx.hasAuthor },
+      { key: "canonical", label: "Canonical URL", test: (ctx) => ctx.hasCanonical },
+      { key: "freshness", label: "datePublished/dateModified", test: (ctx) => ctx.hasFreshness },
+      { key: "citations", label: "External source links", test: (ctx) => ctx.hasCitations }
+    ]
+  }
+};
+
+function buildContext(content) {
+  const plain = /<html|<body/i.test(content) ? stripHtml(content) : content;
+  const sentences = plain.split(/(?<=[.!?])\s+/).filter((s) => s.length > 10);
+  const factSentences = sentences.filter((s) => /\b\d+(\.\d+)?\s*(%|percent|million|billion|x|times)\b/i.test(s));
+
+  return {
+    hasLlmsTxt: false, // Must be checked externally
+    hasJsonLd: /application\/ld\+json/i.test(content),
+    hasDirectAnswer: (() => {
+      const first = plain.split(/\n\s*\n/)[0] || "";
+      return first.length >= 50 && first.length <= 500;
+    })(),
+    hasMetaDescription: /name=["']description["']/i.test(content),
+    hasCanonical: /rel=["']canonical["']/i.test(content),
+    hasAuthor: /\bauthor\b/i.test(content) || /\bdatePublished\b/i.test(content),
+    hasFreshness: /\bdatePublished\b|\bdateModified\b|<time\b/i.test(content),
+    hasCitations: (content.match(/https?:\/\/[^\s"'<>)]+/g) || []).length > 2,
+    hasQaHeadings: /^#{1,6}\s+.+\?/m.test(content) || /<h[1-6][^>]*>.*\?.*<\/h[1-6]>/i.test(content),
+    hasBreadcrumb: /BreadcrumbList/i.test(content),
+    hasSameAs: /sameAs/i.test(content),
+    hasFaqSchema: /FAQPage/i.test(content),
+    hasHowtoSchema: /HowTo/i.test(content),
+    hasListOrTable: /<[ou]l\b/i.test(content) || /<table\b/i.test(content) || /^[-*]\s/m.test(content),
+    hasOgTags: /property=["']og:/i.test(content),
+    hasSemanticHtml: /<(article|section|nav|main|aside|header|footer)\b/i.test(content),
+    entityCount: (plain.match(/\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/g) || []).length,
+    factDensity: sentences.length > 0 ? Math.round((factSentences.length / sentences.length) * 100) : 0,
+    blockedCrawlers: [] // Must be populated externally
+  };
+}
+
+function evaluatePlatform(platform, ctx) {
+  const results = platform.checks.map((check) => ({
+    key: check.key,
+    label: check.label,
+    passed: check.test(ctx)
+  }));
+
+  const passed = results.filter((r) => r.passed).length;
+  const total = results.length;
+  const score = Math.round((passed / total) * 100);
+
+  return {
+    platform: platform.name,
+    crawlers: platform.crawlers,
+    score,
+    passed,
+    total,
+    checks: results,
+    readiness: score >= 80 ? "Ready" : score >= 50 ? "Partial" : "Not ready"
+  };
+}
+
+async function fetchContent(url) {
+  const response = await fetch(url, {
+    redirect: "follow",
+    headers: { "user-agent": "geo-ai-search-optimization/2.2.0" },
+    signal: AbortSignal.timeout(10_000)
+  });
+  if (!response.ok) throw new Error(`Failed to fetch: ${url} (status ${response.status})`);
+  return response.text();
+}
+
+export async function analyzePlatformReadiness(input, options = {}) {
+  let content;
+  let source;
+
+  if (/^https?:\/\//i.test(input)) {
+    content = await fetchContent(input);
+    source = input;
+  } else {
+    const filePath = path.resolve(input);
+    content = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  const ctx = buildContext(content);
+
+  if (options.blockedCrawlers) {
+    ctx.blockedCrawlers = options.blockedCrawlers;
+  }
+  if (options.hasLlmsTxt !== undefined) {
+    ctx.hasLlmsTxt = options.hasLlmsTxt;
+  }
+
+  const platforms = Object.entries(PLATFORMS).map(([key, platform]) => ({
+    key,
+    ...evaluatePlatform(platform, ctx)
+  }));
+
+  const overallScore = Math.round(platforms.reduce((sum, p) => sum + p.score, 0) / platforms.length);
+  const readyCount = platforms.filter((p) => p.readiness === "Ready").length;
+
+  return {
+    kind: "geo-platform-ready",
+    source,
+    overallScore,
+    overallLabel: overallScore >= 80 ? "Well optimized" : overallScore >= 50 ? "Partially optimized" : "Needs work",
+    readyPlatforms: readyCount,
+    totalPlatforms: platforms.length,
+    platforms,
+    summary: `Platform readiness: ${overallScore}/100. ${readyCount}/${platforms.length} platforms ready.`,
+    recommendations: buildPlatformRecommendations(platforms)
+  };
+}
+
+function buildPlatformRecommendations(platforms) {
+  const recs = [];
+  for (const p of platforms) {
+    const failed = p.checks.filter((c) => !c.passed);
+    if (failed.length > 0) {
+      recs.push(`**${p.platform}** (${p.score}/100): Fix ${failed.map((f) => f.label).join(", ")}`);
+    }
+  }
+  return recs;
+}
+
+export function renderPlatformReadyMarkdown(report) {
+  const lines = [
+    "# Multi-Platform Readiness Report",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Overall Score: \`${report.overallScore}/100\` (${report.overallLabel})`,
+    `- Platforms Ready: \`${report.readyPlatforms}/${report.totalPlatforms}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Platform Matrix",
+    "",
+    "| Platform | Score | Status | Passed | Failed |",
+    "|----------|-------|--------|--------|--------|"
+  ];
+
+  for (const p of report.platforms) {
+    const icon = p.readiness === "Ready" ? "✅" : p.readiness === "Partial" ? "⚠️" : "❌";
+    const failedCount = p.total - p.passed;
+    lines.push(`| ${p.platform} | ${p.score}/100 | ${icon} ${p.readiness} | ${p.passed} | ${failedCount} |`);
+  }
+  lines.push("");
+
+  for (const p of report.platforms) {
+    lines.push(`## ${p.platform}`, "");
+    for (const check of p.checks) {
+      const icon = check.passed ? "✅" : "❌";
+      lines.push(`- ${icon} ${check.label}`);
+    }
+    lines.push("");
+  }
+
+  if (report.recommendations.length > 0) {
+    lines.push("## Recommendations", "");
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export async function writePlatformReadyOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/plugins.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Plugin architecture for geo-ai-search-optimization.
+ *
+ * Plugins are JS modules that export a `register(api)` function.
+ * The API object exposes:
+ *   - api.addSignal(name, { pattern, label, weight })
+ *   - api.addCheck(name, { label, maxPoints, passed: (data) => boolean })
+ *   - api.addCommand(name, { description, handler: async (args) => void })
+ *   - api.addScoreRule(name, { label, maxPoints, passed: (scan) => boolean })
+ *
+ * Plugins can be loaded from:
+ *   - .georc.json "plugins" array (module names or paths)
+ *   - Programmatic API via loadPlugins()
+ */
+
+const registry = {
+  signals: {},
+  checks: {},
+  commands: {},
+  scoreRules: []
+};
+
+const api = {
+  addSignal(name, config) {
+    if (!name || !config.pattern) throw new Error(`Plugin signal "${name}" requires a pattern`);
+    registry.signals[name] = {
+      pattern: config.pattern instanceof RegExp ? config.pattern : new RegExp(config.pattern, "i"),
+      label: config.label || name,
+      weight: config.weight || 0
+    };
+  },
+
+  addCheck(name, config) {
+    if (!name || !config.passed) throw new Error(`Plugin check "${name}" requires a passed function`);
+    registry.checks[name] = {
+      label: config.label || name,
+      maxPoints: config.maxPoints || 5,
+      passed: config.passed
+    };
+  },
+
+  addCommand(name, config) {
+    if (!name || !config.handler) throw new Error(`Plugin command "${name}" requires a handler`);
+    registry.commands[name] = {
+      description: config.description || name,
+      handler: config.handler
+    };
+  },
+
+  addScoreRule(name, config) {
+    if (!name || !config.passed) throw new Error(`Plugin score rule "${name}" requires a passed function`);
+    registry.scoreRules.push({
+      key: name,
+      label: config.label || name,
+      maxPoints: config.maxPoints || 5,
+      passed: config.passed
+    });
+  }
+};
+
+export async function loadPlugins(pluginPaths = [], options = {}) {
+  const loaded = [];
+  const errors = [];
+
+  for (const pluginPath of pluginPaths) {
+    try {
+      let resolvedPath;
+
+      if (pluginPath.startsWith(".") || pluginPath.startsWith("/")) {
+        resolvedPath = path.resolve(options.baseDir || ".", pluginPath);
+      } else {
+        // Try as npm module name — resolve from project node_modules
+        const baseDirNodeModules = path.join(options.baseDir || ".", "node_modules", pluginPath);
+        try {
+          await fs.access(baseDirNodeModules);
+          resolvedPath = baseDirNodeModules;
+        } catch {
+          resolvedPath = pluginPath; // Let dynamic import handle it
+        }
+      }
+
+      const pluginModule = await import(resolvedPath);
+      if (typeof pluginModule.register !== "function") {
+        errors.push({ path: pluginPath, error: "Plugin must export a register(api) function" });
+        continue;
+      }
+
+      pluginModule.register(api);
+      loaded.push({ path: pluginPath, name: pluginModule.name || path.basename(pluginPath) });
+    } catch (err) {
+      errors.push({ path: pluginPath, error: err.message });
+    }
+  }
+
+  return { loaded, errors };
+}
+
+export function getPluginRegistry() {
+  return { ...registry };
+}
+
+export function getPluginSignals() {
+  return { ...registry.signals };
+}
+
+export function getPluginChecks() {
+  return { ...registry.checks };
+}
+
+export function getPluginCommands() {
+  return { ...registry.commands };
+}
+
+export function getPluginScoreRules() {
+  return [...registry.scoreRules];
+}
+
+export function resetPluginRegistry() {
+  registry.signals = {};
+  registry.checks = {};
+  registry.commands = {};
+  registry.scoreRules = [];
+}