geo-ai-search-optimization 1.4.2 → 2.2.0

package/src/compare.js

@@ -0,0 +1,175 @@
+import { writeScanOutput } from "./scan.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+/**
+ * Compare two pages across all 12 dimensions.
+ * Produces a side-by-side analysis with delta scoring.
+ */
+
+export async function comparePages(inputA, inputB, options = {}) {
+  const [resultA, resultB] = await Promise.all([
+    fullPageAudit(inputA, options),
+    fullPageAudit(inputB, options)
+  ]);
+
+  const dimensions = {};
+  const allDimKeys = new Set([
+    ...Object.keys(resultA.dimensions),
+    ...Object.keys(resultB.dimensions)
+  ]);
+
+  let aWins = 0;
+  let bWins = 0;
+  let ties = 0;
+
+  for (const key of allDimKeys) {
+    const scoreA = resultA.dimensions[key]?.score ?? 0;
+    const scoreB = resultB.dimensions[key]?.score ?? 0;
+    const delta = scoreA - scoreB;
+    const winner = delta > 0 ? "A" : delta < 0 ? "B" : "tie";
+
+    if (winner === "A") aWins++;
+    else if (winner === "B") bWins++;
+    else ties++;
+
+    dimensions[key] = {
+      scoreA,
+      scoreB,
+      delta,
+      winner,
+      labelA: resultA.dimensions[key]?.label ?? "",
+      labelB: resultB.dimensions[key]?.label ?? ""
+    };
+  }
+
+  const compositeA = resultA.compositeScore;
+  const compositeB = resultB.compositeScore;
+  const compositeDelta = compositeA - compositeB;
+
+  // Identify where each page is stronger
+  const aStrengths = Object.entries(dimensions)
+    .filter(([, d]) => d.delta > 10)
+    .sort((a, b) => b[1].delta - a[1].delta)
+    .map(([key, d]) => ({ dimension: key, delta: d.delta }));
+
+  const bStrengths = Object.entries(dimensions)
+    .filter(([, d]) => d.delta < -10)
+    .sort((a, b) => a[1].delta - b[1].delta)
+    .map(([key, d]) => ({ dimension: key, delta: Math.abs(d.delta) }));
+
+  // Platform comparison
+  const platformComparison = [];
+  if (resultA.platformSummary && resultB.platformSummary) {
+    for (let i = 0; i < resultA.platformSummary.length; i++) {
+      const pA = resultA.platformSummary[i];
+      const pB = resultB.platformSummary[i];
+      if (pA && pB) {
+        platformComparison.push({
+          platform: pA.platform,
+          scoreA: pA.score,
+          scoreB: pB.score,
+          delta: pA.score - pB.score,
+          readinessA: pA.readiness,
+          readinessB: pB.readiness
+        });
+      }
+    }
+  }
+
+  const overallWinner = compositeDelta > 5 ? "A" : compositeDelta < -5 ? "B" : "tie";
+
+  return {
+    kind: "geo-compare",
+    inputA,
+    inputB,
+    compositeA,
+    compositeB,
+    compositeDelta,
+    overallWinner,
+    dimensionWins: { A: aWins, B: bWins, ties },
+    dimensions,
+    aStrengths,
+    bStrengths,
+    platformComparison,
+    summary: overallWinner === "tie"
+      ? `Near parity. A: ${compositeA}/100, B: ${compositeB}/100 (Δ${compositeDelta >= 0 ? "+" : ""}${compositeDelta}).`
+      : `${overallWinner === "A" ? "Page A" : "Page B"} leads. A: ${compositeA}/100, B: ${compositeB}/100 (Δ${compositeDelta >= 0 ? "+" : ""}${compositeDelta}). Dimension wins: A=${aWins}, B=${bWins}, Ties=${ties}.`
+  };
+}
+
+export function renderCompareMarkdown(report) {
+  const lines = [
+    "# GEO Page Comparison",
+    "",
+    `- **Page A**: \`${report.inputA}\``,
+    `- **Page B**: \`${report.inputB}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Composite Scores",
+    "",
+    `| | Page A | Page B | Delta |`,
+    `|--|--------|--------|-------|`,
+    `| **Composite** | **${report.compositeA}** | **${report.compositeB}** | ${report.compositeDelta >= 0 ? "+" : ""}${report.compositeDelta} |`,
+    ""
+  ];
+
+  const dimLabels = {
+    base: "Base", citability: "Citability", eeat: "E-E-A-T", readability: "Readability",
+    headingStructure: "Headings", internalLinks: "Links", socialMeta: "Social",
+    platformReady: "Platforms", schema: "Schema", freshness: "Freshness",
+    security: "Security", topics: "Topics"
+  };
+
+  lines.push(
+    "## Dimension Comparison",
+    "",
+    "| Dimension | Page A | Page B | Δ | Winner |",
+    "|-----------|--------|--------|---|--------|"
+  );
+
+  const sorted = Object.entries(report.dimensions)
+    .sort((a, b) => Math.abs(b[1].delta) - Math.abs(a[1].delta));
+
+  for (const [key, d] of sorted) {
+    const winIcon = d.winner === "A" ? "◀️ A" : d.winner === "B" ? "B ▶️" : "—";
+    lines.push(`| ${dimLabels[key] || key} | ${d.scoreA} | ${d.scoreB} | ${d.delta >= 0 ? "+" : ""}${d.delta} | ${winIcon} |`);
+  }
+  lines.push("");
+
+  if (report.aStrengths.length > 0) {
+    lines.push("## Page A Strengths", "");
+    for (const s of report.aStrengths) {
+      lines.push(`- **${dimLabels[s.dimension] || s.dimension}**: +${s.delta} points ahead`);
+    }
+    lines.push("");
+  }
+
+  if (report.bStrengths.length > 0) {
+    lines.push("## Page B Strengths", "");
+    for (const s of report.bStrengths) {
+      lines.push(`- **${dimLabels[s.dimension] || s.dimension}**: +${s.delta} points ahead`);
+    }
+    lines.push("");
+  }
+
+  if (report.platformComparison.length > 0) {
+    lines.push(
+      "## Platform Readiness Comparison",
+      "",
+      "| Platform | A Score | B Score | Δ | A Status | B Status |",
+      "|----------|---------|---------|---|----------|----------|"
+    );
+    for (const p of report.platformComparison) {
+      lines.push(`| ${p.platform} | ${p.scoreA} | ${p.scoreB} | ${p.delta >= 0 ? "+" : ""}${p.delta} | ${p.readinessA} | ${p.readinessB} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push(`## Verdict`, "", `**Dimension wins**: A=${report.dimensionWins.A}, B=${report.dimensionWins.B}, Ties=${report.dimensionWins.ties}`, "");
+
+  return lines.join("\n");
+}
+
+export async function writeCompareOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/config.js

@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const CONFIG_FILE_NAMES = [".georc.json", "geo.config.json"];
+
+async function findConfigFile(startDir) {
+  let dir = path.resolve(startDir || ".");
+
+  for (let i = 0; i < 10; i++) {
+    for (const name of CONFIG_FILE_NAMES) {
+      const candidate = path.join(dir, name);
+      try {
+        await fs.access(candidate);
+        return candidate;
+      } catch {
+        // continue
+      }
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+export async function loadConfig(options = {}) {
+  const configPath = options.configPath || await findConfigFile(options.startDir || ".");
+
+  if (!configPath) {
+    return { _source: null, _found: false };
+  }
+
+  try {
+    const content = await fs.readFile(configPath, "utf8");
+    const config = JSON.parse(content);
+    return { ...config, _source: configPath, _found: true };
+  } catch (err) {
+    throw new Error(`Failed to read config at ${configPath}: ${err.message}`);
+  }
+}
+
+export async function initConfig(options = {}) {
+  const targetDir = path.resolve(options.targetDir || ".");
+  const outputPath = path.join(targetDir, ".georc.json");
+
+  try {
+    await fs.access(outputPath);
+    if (!options.overwrite) {
+      throw new Error(`Config already exists at ${outputPath}. Use --overwrite to replace.`);
+    }
+  } catch (err) {
+    if (err.message.includes("already exists")) throw err;
+  }
+
+  const config = {
+    $schema: "https://geo-ai-search-optimization.dev/schema/georc.json",
+    site: {
+      name: options.siteName || null,
+      url: options.siteUrl || null
+    },
+    audit: {
+      minScore: options.minScore || 40,
+      maxFileSize: 1_000_000,
+      maxExamples: 5
+    },
+    ci: {
+      minScore: options.minScore || 40,
+      failOnRegression: false,
+      baselineDir: ".geo-data"
+    },
+    crawlers: {
+      strategy: "open"
+    },
+    output: {
+      format: "markdown",
+      dataDir: ".geo-data"
+    },
+    plugins: []
+  };
+
+  await fs.mkdir(targetDir, { recursive: true });
+  await fs.writeFile(outputPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+
+  return { outputPath, config };
+}
+
+export function mergeConfigWithOptions(config, cliOptions) {
+  const merged = { ...cliOptions };
+
+  if (config._found) {
+    if (config.site?.url && !merged.siteUrl) merged.siteUrl = config.site.url;
+    if (config.site?.name && !merged.siteName) merged.siteName = config.site.name;
+    if (config.audit?.minScore !== undefined && merged.minScore === undefined) merged.minScore = config.audit.minScore;
+    if (config.audit?.maxFileSize !== undefined && merged.maxFileSize === undefined) merged.maxFileSize = config.audit.maxFileSize;
+    if (config.audit?.maxExamples !== undefined && merged.maxExamples === undefined) merged.maxExamples = config.audit.maxExamples;
+    if (config.ci?.failOnRegression && merged.failOnRegression === undefined) merged.failOnRegression = config.ci.failOnRegression;
+    if (config.output?.format && !merged.format) merged.format = config.output.format;
+    if (config.output?.dataDir && !merged.dataDir) merged.dataDir = config.output.dataDir;
+    if (config.crawlers?.strategy && !merged.strategy) merged.strategy = config.crawlers.strategy;
+  }
+
+  return merged;
+}

package/src/content-gap.js

@@ -0,0 +1,170 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { auditPage } from "./page-audit.js";
+import { writeScanOutput } from "./scan.js";
+
+const SIGNAL_LABELS = {
+  title: "标题",
+  meta_description: "Meta Description",
+  canonical: "Canonical",
+  json_ld: "结构化数据 (JSON-LD)",
+  faq_schema: "FAQ Schema",
+  howto_schema: "HowTo Schema",
+  article_schema: "Article Schema",
+  organization_schema: "Organization Schema",
+  product_schema: "Product Schema",
+  breadcrumb_schema: "Breadcrumb Schema",
+  author_markers: "作者 / 发布时间",
+  qa_headings: "问答式标题",
+  comparison_intent: "比较 / 替代内容",
+  original_research: "原创研究 / 方法论",
+  citations: "引用 / 来源链接"
+};
+
+const SIGNAL_PRIORITIES = {
+  json_ld: 1,
+  qa_headings: 1,
+  author_markers: 2,
+  citations: 2,
+  original_research: 2,
+  comparison_intent: 3,
+  faq_schema: 3,
+  article_schema: 3,
+  canonical: 4,
+  meta_description: 4,
+  title: 4,
+  breadcrumb_schema: 5,
+  howto_schema: 5,
+  organization_schema: 5,
+  product_schema: 5
+};
+
+const CONTENT_SUGGESTIONS = {
+  json_ld: "在页面中加入与内容一致的 JSON-LD 结构化数据。",
+  qa_headings: "增加问答式 H2/H3 标题，覆盖用户常问的问题。",
+  author_markers: "补上作者、审校者、发布时间或更新时间。",
+  citations: "为关键结论和数据补上来源链接。",
+  original_research: "创建包含第一方数据、方法论或 benchmark 的内容。",
+  comparison_intent: "新增 comparison / vs / alternatives 内容页面。",
+  faq_schema: "实现 FAQ Schema 标记。",
+  article_schema: "实现 Article Schema 标记。",
+  canonical: "确保页面有正确的 canonical 标签。",
+  meta_description: "补齐 meta description。",
+  breadcrumb_schema: "增加 breadcrumb schema。"
+};
+
+async function loadBenchmarkJson(filePath) {
+  const raw = await fs.readFile(path.resolve(filePath), "utf8");
+  const data = JSON.parse(raw);
+  if (data.kind === "geo-benchmark") return data;
+  throw new Error("提供的 JSON 不是有效的 benchmark 结果");
+}
+
+export async function analyzeContentGap(ownUrl, competitorUrls, options = {}) {
+  let ownAudit;
+  let competitorAudits;
+
+  if (options.benchmarkJson) {
+    const benchmark = await loadBenchmarkJson(options.benchmarkJson);
+    const ownPageResult = benchmark.pageResults.find(
+      (r) => r.input === benchmark.ownUrl || r.reference === benchmark.ownUrl
+    );
+    if (!ownPageResult) throw new Error("benchmark JSON 中找不到自己的审计结果");
+    ownAudit = ownPageResult;
+    competitorAudits = benchmark.pageResults.filter((r) => r !== ownPageResult);
+  } else {
+    ownAudit = await auditPage(ownUrl, {});
+    competitorAudits = [];
+    for (const url of competitorUrls) {
+      try {
+        competitorAudits.push(await auditPage(url, {}));
+      } catch {
+        // skip failed
+      }
+    }
+  }
+
+  // Find gaps: signals competitors have that we don't
+  const gaps = [];
+  const allSignals = Object.keys(ownAudit.signals);
+
+  for (const signal of allSignals) {
+    const ownHas = ownAudit.signals[signal]?.count > 0;
+    if (ownHas) continue;
+
+    const competitorsWithSignal = competitorAudits.filter(
+      (audit) => audit.signals[signal]?.count > 0
+    );
+
+    if (competitorsWithSignal.length > 0) {
+      gaps.push({
+        signal,
+        label: SIGNAL_LABELS[signal] || signal,
+        priority: SIGNAL_PRIORITIES[signal] || 5,
+        competitorCount: competitorsWithSignal.length,
+        totalCompetitors: competitorAudits.length,
+        suggestion: CONTENT_SUGGESTIONS[signal] || `补齐 ${signal} 信号。`
+      });
+    }
+  }
+
+  // Sort by priority (lower = more important)
+  gaps.sort((a, b) => a.priority - b.priority);
+
+  // Build content backlog
+  const backlog = gaps.map((gap, index) => ({
+    rank: index + 1,
+    signal: gap.signal,
+    label: gap.label,
+    action: gap.suggestion,
+    urgency: gap.priority <= 2 ? "高" : gap.priority <= 3 ? "中" : "低",
+    competitorCoverage: `${gap.competitorCount}/${gap.totalCompetitors}`
+  }));
+
+  return {
+    kind: "geo-content-gap",
+    ownUrl: ownUrl || ownAudit.input,
+    ownScore: ownAudit.score.score,
+    competitorCount: competitorAudits.length,
+    gapCount: gaps.length,
+    gaps,
+    backlog,
+    summary: gaps.length === 0
+      ? "你的页面信号覆盖已经与竞品持平或领先，当前没有明显缺口。"
+      : `发现 ${gaps.length} 个信号缺口，最高优先级：${gaps[0].label}。`
+  };
+}
+
+export function renderContentGapMarkdown(report) {
+  const lines = [
+    "# GEO 内容缺口分析",
+    "",
+    `- 你的 URL：\`${report.ownUrl}\``,
+    `- 你的分数：\`${report.ownScore}/100\``,
+    `- 竞品数量：\`${report.competitorCount}\``,
+    `- 缺口数量：\`${report.gapCount}\``,
+    `- 总结：${report.summary}`,
+    ""
+  ];
+
+  if (report.gaps.length > 0) {
+    lines.push("## 缺口矩阵", "", "| 信号 | 竞品覆盖 | 紧急度 | 建议 |", "|------|----------|--------|------|");
+    for (const gap of report.gaps) {
+      lines.push(`| ${gap.label} | ${gap.competitorCount}/${gap.totalCompetitors} | P${gap.priority} | ${gap.suggestion} |`);
+    }
+  }
+
+  if (report.backlog.length > 0) {
+    lines.push("", "## 内容 Backlog", "");
+    for (const item of report.backlog) {
+      lines.push(`${item.rank}. **${item.label}**（${item.urgency}）— ${item.action}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeContentGapOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}