geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/full-audit.js

@@ -0,0 +1,269 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+import { auditProject } from "./audit.js";
+import { analyzeCrawlers } from "./crawlers.js";
+import { validateLlmsTxt } from "./validate-llms.js";
+import { fullPageAudit } from "./full-page-audit.js";
+
+async function runSafe(label, fn) {
+  try {
+    return { ok: true, data: await fn() };
+  } catch (err) {
+    return { ok: false, error: err.message, label };
+  }
+}
+
+async function findSpecialFile(root, filename) {
+  const candidates = [
+    path.join(root, filename),
+    path.join(root, "public", filename),
+    path.join(root, "static", filename),
+    path.join(root, "dist", filename),
+    path.join(root, "out", filename)
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+      // continue
+    }
+  }
+
+  return null;
+}
+
+export async function fullAudit(input, options = {}) {
+  const root = path.resolve(input);
+
+  // Phase 1: Run base project audit
+  const baseAudit = await auditProject(root, options);
+
+  // Phase 2: Run infrastructure analyses in parallel
+  const robotsPath = await findSpecialFile(root, "robots.txt");
+  const llmsPath = await findSpecialFile(root, "llms.txt");
+
+  const [crawlersResult, llmsResult] = await Promise.all([
+    robotsPath
+      ? runSafe("crawlers", () => analyzeCrawlers(robotsPath))
+      : { ok: true, data: { score: 0, crawlers: [], summary: "No robots.txt found in project.", recommendation: "" } },
+    llmsPath
+      ? runSafe("validate-llms", () => validateLlmsTxt(llmsPath))
+      : { ok: true, data: { score: 0, found: false, summary: "No llms.txt found in project." } }
+  ]);
+
+  // Phase 3: Sample page audits (if URLs or HTML files provided)
+  const sampleUrls = options.sampleUrls || [];
+  const samplePages = [];
+
+  if (sampleUrls.length > 0) {
+    const concurrency = options.concurrency || 2;
+    const chunks = [];
+    for (let i = 0; i < sampleUrls.length; i += concurrency) {
+      chunks.push(sampleUrls.slice(i, i + concurrency));
+    }
+
+    for (const chunk of chunks) {
+      const results = await Promise.all(
+        chunk.map((url) => runSafe(`page:${url}`, () => fullPageAudit(url, options)))
+      );
+      for (const result of results) {
+        if (result.ok) {
+          samplePages.push(result.data);
+        }
+      }
+    }
+  }
+
+  // Phase 4: Compute enhanced score
+  const infraScores = {
+    base: baseAudit.score,
+    crawlers: crawlersResult.ok ? crawlersResult.data.score : 0,
+    llmsValidation: llmsResult.ok ? llmsResult.data.score : 0
+  };
+
+  // Composite: base audit (60%) + crawler health (20%) + llms.txt quality (20%)
+  const infraComposite = Math.round(
+    infraScores.base * 0.6 +
+    infraScores.crawlers * 0.2 +
+    infraScores.llmsValidation * 0.2
+  );
+
+  // Page-level composite (average of sampled pages)
+  const pageComposite = samplePages.length > 0
+    ? Math.round(samplePages.reduce((sum, p) => sum + p.compositeScore, 0) / samplePages.length)
+    : null;
+
+  // Overall composite
+  const overallComposite = pageComposite !== null
+    ? Math.round(infraComposite * 0.5 + pageComposite * 0.5)
+    : infraComposite;
+
+  const overallLabel = overallComposite >= 80 ? "Strong"
+    : overallComposite >= 60 ? "Moderate"
+    : overallComposite >= 40 ? "Weak"
+    : "Very weak";
+
+  // Merge all recommendations
+  const allRecs = [];
+  if (baseAudit.actionPlan) {
+    allRecs.push(...baseAudit.actionPlan.map((t) => ({
+      priority: t.priority,
+      source: "project-audit",
+      action: t.action,
+      owner: t.owner,
+      area: t.area
+    })));
+  }
+  if (crawlersResult.ok && crawlersResult.data.blocked?.length > 0) {
+    allRecs.push({
+      priority: "P1",
+      source: "crawlers",
+      action: `Unblock ${crawlersResult.data.blocked.length} AI crawler(s): ${crawlersResult.data.blocked.join(", ")}`,
+      owner: "Engineering",
+      area: "AI Crawler Access"
+    });
+  }
+  if (llmsResult.ok && llmsResult.data.issues?.length > 0) {
+    allRecs.push({
+      priority: "P1",
+      source: "llms-validation",
+      action: `Fix ${llmsResult.data.issues.length} llms.txt issue(s): ${llmsResult.data.issues.map((i) => i.message).join("; ")}`,
+      owner: "Engineering / SEO",
+      area: "llms.txt"
+    });
+  }
+
+  // Page-level top issues
+  for (const page of samplePages) {
+    for (const rec of (page.recommendations || []).slice(0, 3)) {
+      allRecs.push({
+        priority: "P2",
+        source: `page:${page.input}`,
+        action: rec.rec,
+        owner: "Content / SEO",
+        area: rec.source
+      });
+    }
+  }
+
+  const errors = [];
+  if (!crawlersResult.ok) errors.push({ component: "crawlers", error: crawlersResult.error });
+  if (!llmsResult.ok) errors.push({ component: "validate-llms", error: llmsResult.error });
+
+  return {
+    kind: "geo-full-audit",
+    root,
+    overallScore: overallComposite,
+    overallLabel,
+    infraScore: infraComposite,
+    pageScore: pageComposite,
+    scores: {
+      base: infraScores.base,
+      crawlers: infraScores.crawlers,
+      llmsValidation: infraScores.llmsValidation,
+      pageAverage: pageComposite
+    },
+    baseAudit,
+    crawlers: crawlersResult.ok ? crawlersResult.data : null,
+    llmsValidation: llmsResult.ok ? llmsResult.data : null,
+    samplePages,
+    actionPlan: allRecs.slice(0, 20),
+    errors,
+    summary: `Full GEO Audit: ${overallComposite}/100 (${overallLabel}). Infrastructure: ${infraComposite}/100. ${samplePages.length > 0 ? `Page quality: ${pageComposite}/100 (${samplePages.length} pages sampled).` : "No page samples."}`
+  };
+}
+
+export function renderFullAuditMarkdown(report) {
+  const lines = [
+    "# GEO Full Audit Report",
+    "",
+    `- Project: \`${report.root}\``,
+    `- **Overall GEO Score: \`${report.overallScore}/100\` (${report.overallLabel})**`,
+    `- Infrastructure Score: \`${report.infraScore}/100\``,
+    report.pageScore !== null ? `- Page Quality Score: \`${report.pageScore}/100\` (${report.samplePages.length} pages)` : "- Page Quality: Not sampled",
+    `- Summary: ${report.summary}`,
+    "",
+    "## Score Breakdown",
+    "",
+    "| Component | Score | Weight |",
+    "|-----------|-------|--------|",
+    `| 🏗️ Base Project Audit | ${report.scores.base}/100 | 60% of infra |`,
+    `| 🤖 AI Crawler Access | ${report.scores.crawlers}/100 | 20% of infra |`,
+    `| 📄 llms.txt Validation | ${report.scores.llmsValidation}/100 | 20% of infra |`
+  ];
+
+  if (report.pageScore !== null) {
+    lines.push(`| 📊 Page Quality Average | ${report.scores.pageAverage}/100 | 50% of overall |`);
+  }
+
+  // Crawler summary
+  if (report.crawlers) {
+    lines.push("", "## AI Crawler Access", "");
+    const blocked = report.crawlers.crawlers?.filter((c) => c.status === "blocked") || [];
+    const allowed = report.crawlers.crawlers?.filter((c) => c.status === "allowed") || [];
+    lines.push(`- Allowed: \`${allowed.length}\` | Blocked: \`${blocked.length}\` | Score: \`${report.crawlers.score}/100\``);
+    if (blocked.length > 0) {
+      lines.push(`- ⚠️ Blocked crawlers: ${blocked.map((c) => `**${c.crawler}** (${c.engine})`).join(", ")}`);
+    }
+  }
+
+  // llms.txt summary
+  if (report.llmsValidation) {
+    lines.push("", "## llms.txt Status", "");
+    if (report.llmsValidation.found) {
+      lines.push(`- Score: \`${report.llmsValidation.score}/100\` (${report.llmsValidation.scoreLabel})`);
+      if (report.llmsValidation.issues?.length > 0) {
+        lines.push(`- Issues: ${report.llmsValidation.issues.map((i) => i.message).join("; ")}`);
+      }
+    } else {
+      lines.push("- ❌ No llms.txt found. Run `geo-ai-search-optimization init-llms` to create one.");
+    }
+  }
+
+  // Base audit areas
+  if (report.baseAudit?.areas) {
+    lines.push("", "## Issue Areas (Project Level)", "");
+    for (const area of report.baseAudit.areas) {
+      const icon = area.severity === "高" ? "🔴" : area.severity === "中" ? "🟡" : "🟢";
+      lines.push(`- ${icon} **${area.title}** — ${area.status}`);
+      if (area.issues.length > 0) {
+        lines.push(`  ${area.summary}`);
+      }
+    }
+  }
+
+  // Sample page results
+  if (report.samplePages.length > 0) {
+    lines.push("", "## Sampled Page Results", "", "| Page | Composite | Base | Citability | E-E-A-T | Readability |", "|------|-----------|------|------------|---------|-------------|");
+    for (const page of report.samplePages) {
+      const d = page.dimensions;
+      const shortInput = page.input.length > 40 ? `...${page.input.slice(-37)}` : page.input;
+      lines.push(`| ${shortInput} | **${page.compositeScore}** | ${d.base?.score ?? "—"} | ${d.citability?.score ?? "—"} | ${d.eeat?.score ?? "—"} | ${d.readability?.score ?? "—"} |`);
+    }
+  }
+
+  // Unified action plan
+  if (report.actionPlan.length > 0) {
+    lines.push("", "## Unified Action Plan", "");
+    for (const task of report.actionPlan) {
+      lines.push(`- **${task.priority}** [${task.source}] ${task.action}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    lines.push("", "## Errors", "");
+    for (const err of report.errors) {
+      lines.push(`- ⚠️ ${err.component}: ${err.error}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeFullAuditOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/full-page-audit.js

@@ -0,0 +1,273 @@
+import { writeScanOutput } from "./scan.js";
+import { auditPage } from "./page-audit.js";
+import { analyzeCitability } from "./citability.js";
+import { analyzeEeat } from "./eeat.js";
+import { analyzeReadability } from "./readability.js";
+import { analyzeHeadingStructure } from "./heading-structure.js";
+import { analyzeInternalLinks } from "./internal-links.js";
+import { analyzeSocialMeta } from "./social-meta.js";
+import { analyzePlatformReadiness } from "./platform-ready.js";
+import { validateSchema } from "./validate-schema.js";
+import { analyzeFreshness } from "./freshness.js";
+import { analyzeSecurity } from "./security.js";
+import { analyzeTopics } from "./topics.js";
+
+const DIMENSION_WEIGHTS = {
+  base: 0.15,
+  citability: 0.12,
+  eeat: 0.12,
+  readability: 0.08,
+  headingStructure: 0.06,
+  socialMeta: 0.05,
+  internalLinks: 0.05,
+  platformReady: 0.08,
+  schema: 0.07,
+  freshness: 0.08,
+  security: 0.07,
+  topics: 0.07
+};
+
+async function runSafe(label, fn) {
+  try {
+    return { ok: true, data: await fn() };
+  } catch (err) {
+    return { ok: false, error: err.message, label };
+  }
+}
+
+export async function fullPageAudit(input, options = {}) {
+  // Run all analyses in parallel (12 dimensions)
+  const [
+    baseResult,
+    citabilityResult,
+    eeatResult,
+    readabilityResult,
+    headingResult,
+    linksResult,
+    socialResult,
+    platformResult,
+    schemaResult,
+    freshnessResult,
+    securityResult,
+    topicsResult
+  ] = await Promise.all([
+    runSafe("base", () => auditPage(input, options)),
+    runSafe("citability", () => analyzeCitability(input)),
+    runSafe("eeat", () => analyzeEeat(input)),
+    runSafe("readability", () => analyzeReadability(input)),
+    runSafe("heading-structure", () => analyzeHeadingStructure(input)),
+    runSafe("internal-links", () => analyzeInternalLinks(input, { baseUrl: options.baseUrl })),
+    runSafe("social-meta", () => analyzeSocialMeta(input)),
+    runSafe("platform-ready", () => analyzePlatformReadiness(input)),
+    runSafe("validate-schema", () => validateSchema(input)),
+    runSafe("freshness", () => analyzeFreshness(input)),
+    runSafe("security", () => analyzeSecurity(input)),
+    runSafe("topics", () => analyzeTopics(input))
+  ]);
+
+  const dimensions = {};
+  const errors = [];
+
+  function addDimension(key, result, scoreField) {
+    if (result.ok) {
+      dimensions[key] = {
+        score: result.data[scoreField || "score"],
+        label: result.data.scoreLabel || result.data[scoreField + "Label"] || "",
+        summary: result.data.summary || ""
+      };
+    } else {
+      errors.push({ dimension: key, error: result.error });
+      dimensions[key] = { score: 0, label: "Error", summary: result.error };
+    }
+  }
+
+  // Base audit score
+  if (baseResult.ok) {
+    dimensions.base = {
+      score: baseResult.data.score.score,
+      label: baseResult.data.scoreLabel,
+      summary: baseResult.data.summary
+    };
+  } else {
+    errors.push({ dimension: "base", error: baseResult.error });
+    dimensions.base = { score: 0, label: "Error", summary: baseResult.error };
+  }
+
+  addDimension("citability", citabilityResult);
+  addDimension("eeat", eeatResult);
+  addDimension("readability", readabilityResult);
+  addDimension("headingStructure", headingResult);
+  addDimension("internalLinks", linksResult);
+  addDimension("socialMeta", socialResult);
+  addDimension("platformReady", platformResult, "overallScore");
+  addDimension("schema", schemaResult);
+  addDimension("freshness", freshnessResult);
+  addDimension("security", securityResult);
+  addDimension("topics", topicsResult);
+
+  // Compute composite score
+  let compositeScore = 0;
+  for (const [key, weight] of Object.entries(DIMENSION_WEIGHTS)) {
+    const dimScore = dimensions[key]?.score || 0;
+    compositeScore += dimScore * weight;
+  }
+  compositeScore = Math.round(compositeScore);
+
+  const compositeLabel = compositeScore >= 80 ? "Strong"
+    : compositeScore >= 60 ? "Moderate"
+    : compositeScore >= 40 ? "Weak"
+    : "Very weak";
+
+  // Build top issues across all dimensions
+  const topIssues = [];
+  if (baseResult.ok && baseResult.data.problemAreas) {
+    for (const area of baseResult.data.problemAreas) {
+      topIssues.push(...area.issues.map((i) => ({ source: "base", severity: area.severity, issue: i })));
+    }
+  }
+  if (eeatResult.ok && eeatResult.data.recommendations) {
+    for (const rec of eeatResult.data.recommendations.slice(0, 3)) {
+      topIssues.push({ source: "eeat", severity: "中", issue: rec });
+    }
+  }
+  if (citabilityResult.ok && citabilityResult.data.recommendations) {
+    for (const rec of citabilityResult.data.recommendations.slice(0, 3)) {
+      topIssues.push({ source: "citability", severity: "中", issue: rec });
+    }
+  }
+  if (socialResult.ok && socialResult.data.recommendations) {
+    for (const rec of socialResult.data.recommendations.slice(0, 2)) {
+      topIssues.push({ source: "social-meta", severity: "中", issue: rec });
+    }
+  }
+
+  // Build consolidated recommendations
+  const allRecs = [];
+  if (baseResult.ok) allRecs.push(...baseResult.data.recommendedBlocks.map((r) => ({ source: "base", rec: r })));
+  if (citabilityResult.ok) allRecs.push(...citabilityResult.data.recommendations.map((r) => ({ source: "citability", rec: r })));
+  if (eeatResult.ok) allRecs.push(...eeatResult.data.recommendations.map((r) => ({ source: "eeat", rec: r })));
+  if (readabilityResult.ok) allRecs.push(...readabilityResult.data.recommendations.map((r) => ({ source: "readability", rec: r })));
+  if (headingResult.ok) allRecs.push(...headingResult.data.recommendations.map((r) => ({ source: "heading", rec: r })));
+  if (socialResult.ok) allRecs.push(...socialResult.data.recommendations.map((r) => ({ source: "social", rec: r })));
+  if (freshnessResult.ok) allRecs.push(...freshnessResult.data.recommendations.map((r) => ({ source: "freshness", rec: r })));
+  if (securityResult.ok) allRecs.push(...securityResult.data.recommendations.map((r) => ({ source: "security", rec: r })));
+  if (topicsResult.ok) allRecs.push(...topicsResult.data.recommendations.map((r) => ({ source: "topics", rec: r })));
+
+  // Prioritize: dedupe and cap
+  const seenRecs = new Set();
+  const prioritizedRecs = allRecs.filter((r) => {
+    const key = r.rec.slice(0, 50);
+    if (seenRecs.has(key)) return false;
+    seenRecs.add(key);
+    return true;
+  }).slice(0, 15);
+
+  // Build platform readiness summary
+  const platformSummary = platformResult.ok
+    ? platformResult.data.platforms.map((p) => ({ platform: p.platform, score: p.score, readiness: p.readiness }))
+    : [];
+
+  return {
+    kind: "geo-full-page-audit",
+    input,
+    source: baseResult.ok ? baseResult.data.reference : input,
+    compositeScore,
+    compositeLabel,
+    dimensions,
+    platformSummary,
+    topIssues: topIssues.slice(0, 12),
+    recommendations: prioritizedRecs,
+    errors,
+    // Embed full sub-reports for JSON consumers
+    details: {
+      base: baseResult.ok ? baseResult.data : null,
+      citability: citabilityResult.ok ? citabilityResult.data : null,
+      eeat: eeatResult.ok ? eeatResult.data : null,
+      readability: readabilityResult.ok ? readabilityResult.data : null,
+      headingStructure: headingResult.ok ? headingResult.data : null,
+      internalLinks: linksResult.ok ? linksResult.data : null,
+      socialMeta: socialResult.ok ? socialResult.data : null,
+      platformReady: platformResult.ok ? platformResult.data : null,
+      schema: schemaResult.ok ? schemaResult.data : null,
+      freshness: freshnessResult.ok ? freshnessResult.data : null,
+      security: securityResult.ok ? securityResult.data : null,
+      topics: topicsResult.ok ? topicsResult.data : null
+    },
+    summary: `Composite GEO Score: ${compositeScore}/100 (${compositeLabel}). ${Object.entries(dimensions).filter(([, d]) => d.score < 40).length} dimension(s) need attention.`
+  };
+}
+
+export function renderFullPageAuditMarkdown(report) {
+  const lines = [
+    "# GEO Full Page Audit",
+    "",
+    `- Input: \`${report.input}\``,
+    `- Source: \`${report.source}\``,
+    `- **Composite GEO Score: \`${report.compositeScore}/100\` (${report.compositeLabel})**`,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Dimension Scores",
+    "",
+    "| Dimension | Score | Weight | Label |",
+    "|-----------|-------|--------|-------|"
+  ];
+
+  const dimLabels = {
+    base: "Base Audit",
+    citability: "Citability",
+    eeat: "E-E-A-T",
+    readability: "Readability",
+    headingStructure: "Heading Structure",
+    internalLinks: "Internal Links",
+    socialMeta: "Social Meta",
+    platformReady: "Platform Readiness",
+    schema: "Schema Validation",
+    freshness: "Content Freshness",
+    security: "Security",
+    topics: "Topic Coverage"
+  };
+
+  for (const [key, weight] of Object.entries(DIMENSION_WEIGHTS)) {
+    const dim = report.dimensions[key] || { score: 0, label: "—" };
+    const icon = dim.score >= 70 ? "🟢" : dim.score >= 40 ? "🟡" : "🔴";
+    lines.push(`| ${icon} ${dimLabels[key] || key} | ${dim.score}/100 | ${Math.round(weight * 100)}% | ${dim.label} |`);
+  }
+
+  if (report.platformSummary.length > 0) {
+    lines.push("", "## Platform Readiness", "");
+    for (const p of report.platformSummary) {
+      const icon = p.readiness === "Ready" ? "✅" : p.readiness === "Partial" ? "⚠️" : "❌";
+      lines.push(`- ${icon} **${p.platform}**: ${p.score}/100 (${p.readiness})`);
+    }
+  }
+
+  if (report.topIssues.length > 0) {
+    lines.push("", "## Top Issues", "");
+    for (const issue of report.topIssues) {
+      const severity = issue.severity === "高" ? "🔴" : "🟡";
+      lines.push(`- ${severity} [${issue.source}] ${issue.issue}`);
+    }
+  }
+
+  if (report.recommendations.length > 0) {
+    lines.push("", "## Prioritized Recommendations", "");
+    for (let i = 0; i < report.recommendations.length; i++) {
+      const rec = report.recommendations[i];
+      lines.push(`${i + 1}. [${rec.source}] ${rec.rec}`);
+    }
+  }
+
+  if (report.errors.length > 0) {
+    lines.push("", "## Errors", "");
+    for (const err of report.errors) {
+      lines.push(`- ⚠️ ${err.dimension}: ${err.error}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeFullPageAuditOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}