geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/sitemap.js

@@ -0,0 +1,323 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+function parseXmlTag(xml, tag) {
+  const results = [];
+  const regex = new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, "gi");
+  let match;
+  while ((match = regex.exec(xml)) !== null) {
+    results.push(match[1].trim());
+  }
+  return results;
+}
+
+function extractTextContent(xml, tag) {
+  const match = xml.match(new RegExp(`<${tag}[^>]*>([^<]*)</${tag}>`, "i"));
+  return match ? match[1].trim() : null;
+}
+
+function parseUrlEntries(sitemapXml) {
+  const urlBlocks = parseXmlTag(sitemapXml, "url");
+  return urlBlocks.map((block) => ({
+    loc: extractTextContent(block, "loc"),
+    lastmod: extractTextContent(block, "lastmod"),
+    changefreq: extractTextContent(block, "changefreq"),
+    priority: extractTextContent(block, "priority")
+  })).filter((entry) => entry.loc);
+}
+
+function parseSitemapIndex(xml) {
+  const sitemapBlocks = parseXmlTag(xml, "sitemap");
+  return sitemapBlocks.map((block) => ({
+    loc: extractTextContent(block, "loc"),
+    lastmod: extractTextContent(block, "lastmod")
+  })).filter((entry) => entry.loc);
+}
+
+function isSitemapIndex(xml) {
+  return /<sitemapindex/i.test(xml);
+}
+
+function analyzeUrls(entries) {
+  const total = entries.length;
+  const withLastmod = entries.filter((e) => e.lastmod).length;
+  const withChangefreq = entries.filter((e) => e.changefreq).length;
+  const withPriority = entries.filter((e) => e.priority).length;
+
+  // Date analysis
+  const dates = entries
+    .filter((e) => e.lastmod)
+    .map((e) => {
+      try { return new Date(e.lastmod); } catch { return null; }
+    })
+    .filter((d) => d && !Number.isNaN(d.getTime()));
+
+  const now = new Date();
+  const ageInDays = dates.map((d) => Math.floor((now - d) / (1000 * 60 * 60 * 24)));
+
+  const freshCount = ageInDays.filter((d) => d <= 30).length;
+  const recentCount = ageInDays.filter((d) => d > 30 && d <= 180).length;
+  const staleCount = ageInDays.filter((d) => d > 180 && d <= 365).length;
+  const oldCount = ageInDays.filter((d) => d > 365).length;
+
+  // Priority distribution
+  const priorities = entries.filter((e) => e.priority).map((e) => Number.parseFloat(e.priority));
+  const avgPriority = priorities.length > 0
+    ? Math.round((priorities.reduce((a, b) => a + b, 0) / priorities.length) * 100) / 100
+    : null;
+
+  // Changefreq distribution
+  const changefreqDist = {};
+  for (const entry of entries) {
+    if (entry.changefreq) {
+      changefreqDist[entry.changefreq] = (changefreqDist[entry.changefreq] || 0) + 1;
+    }
+  }
+
+  // URL pattern analysis
+  const pathDepths = entries.map((e) => {
+    try { return new URL(e.loc).pathname.split("/").filter(Boolean).length; } catch { return 0; }
+  });
+  const avgDepth = pathDepths.length > 0
+    ? Math.round((pathDepths.reduce((a, b) => a + b, 0) / pathDepths.length) * 10) / 10
+    : 0;
+
+  return {
+    total,
+    withLastmod,
+    withChangefreq,
+    withPriority,
+    lastmodCoverage: total > 0 ? Math.round((withLastmod / total) * 100) : 0,
+    freshness: { fresh: freshCount, recent: recentCount, stale: staleCount, old: oldCount },
+    avgPriority,
+    changefreqDistribution: changefreqDist,
+    avgDepth,
+    maxDepth: pathDepths.length > 0 ? Math.max(...pathDepths) : 0
+  };
+}
+
+function validateSitemap(xml, entries, options = {}) {
+  const issues = [];
+  const warnings = [];
+
+  if (!xml.includes('<?xml')) {
+    issues.push({ severity: "error", message: "Missing XML declaration" });
+  }
+
+  if (!/<urlset|<sitemapindex/i.test(xml)) {
+    issues.push({ severity: "error", message: "Missing <urlset> or <sitemapindex> root element" });
+  }
+
+  if (entries.length === 0 && !options.isIndex) {
+    issues.push({ severity: "error", message: "Sitemap contains no URL entries" });
+  }
+
+  if (entries.length > 50000) {
+    issues.push({ severity: "error", message: `Sitemap exceeds 50,000 URL limit (${entries.length} found). Split into multiple sitemaps.` });
+  }
+
+  const urlStats = analyzeUrls(entries);
+  if (urlStats.lastmodCoverage < 50 && entries.length > 0) {
+    warnings.push({ severity: "warning", message: `Only ${urlStats.lastmodCoverage}% of URLs have lastmod. Add dates for better crawl efficiency.` });
+  }
+
+  if (urlStats.freshness.old > entries.length * 0.3) {
+    warnings.push({ severity: "warning", message: `${urlStats.freshness.old} URLs have lastmod older than 1 year. Review and update stale content.` });
+  }
+
+  const invalidUrls = entries.filter((e) => {
+    try { new URL(e.loc); return false; } catch { return true; }
+  });
+  if (invalidUrls.length > 0) {
+    issues.push({ severity: "error", message: `${invalidUrls.length} URL(s) are malformed` });
+  }
+
+  const duplicates = entries.length - new Set(entries.map((e) => e.loc)).size;
+  if (duplicates > 0) {
+    warnings.push({ severity: "warning", message: `${duplicates} duplicate URL(s) found` });
+  }
+
+  return { issues, warnings };
+}
+
+function computeScore(entries, validation) {
+  if (entries.length === 0) return 0;
+
+  let score = 40; // Base: sitemap exists and has entries
+  const urlStats = analyzeUrls(entries);
+
+  score += Math.min(Math.round(urlStats.lastmodCoverage * 0.2), 20);
+  if (urlStats.freshness.fresh > 0) score += 10;
+  if (urlStats.withPriority > entries.length * 0.5) score += 10;
+  if (urlStats.withChangefreq > entries.length * 0.5) score += 5;
+
+  score -= validation.issues.length * 10;
+  score -= validation.warnings.length * 3;
+
+  if (entries.length >= 10) score += 5;
+  if (entries.length >= 50) score += 5;
+  if (entries.length >= 100) score += 5;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+async function fetchSitemap(url) {
+  const parsedUrl = new URL(url);
+  const sitemapUrl = `${parsedUrl.protocol}//${parsedUrl.host}/sitemap.xml`;
+  const response = await fetch(sitemapUrl, {
+    redirect: "follow",
+    headers: { "user-agent": "geo-ai-search-optimization/2.2.0" },
+    signal: AbortSignal.timeout(15_000)
+  });
+  if (!response.ok) return { found: false, url: sitemapUrl, content: "" };
+  return { found: true, url: sitemapUrl, content: await response.text() };
+}
+
+export async function analyzeSitemap(input, options = {}) {
+  let xml;
+  let source;
+
+  if (/^https?:\/\//i.test(input)) {
+    const result = await fetchSitemap(input);
+    if (!result.found) {
+      return {
+        kind: "geo-sitemap",
+        source: result.url,
+        found: false,
+        score: 0,
+        scoreLabel: "Not found",
+        summary: `No sitemap found at ${result.url}`,
+        entries: [],
+        urlStats: null,
+        validation: { issues: [{ severity: "error", message: "Sitemap not found" }], warnings: [] },
+        recommendations: ["Create an XML sitemap and submit it to search engines."]
+      };
+    }
+    xml = result.content;
+    source = result.url;
+  } else {
+    const filePath = path.resolve(input);
+    xml = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  const isIndex = isSitemapIndex(xml);
+  let entries;
+  let childSitemaps = [];
+
+  if (isIndex) {
+    childSitemaps = parseSitemapIndex(xml);
+    entries = []; // Index doesn't have direct URL entries
+  } else {
+    entries = parseUrlEntries(xml);
+  }
+
+  const urlStats = entries.length > 0 ? analyzeUrls(entries) : null;
+  const validation = validateSitemap(xml, entries, { isIndex });
+  const score = isIndex ? 60 : computeScore(entries, validation); // Index gets base 60
+
+  const recommendations = [];
+  if (isIndex && childSitemaps.length === 0) {
+    recommendations.push("Sitemap index is empty. Add child sitemap references.");
+  }
+  if (!isIndex && entries.length === 0) {
+    recommendations.push("Sitemap has no URL entries. Add your important pages.");
+  }
+  if (urlStats && urlStats.lastmodCoverage < 80) {
+    recommendations.push("Add lastmod dates to all URLs for better crawl scheduling.");
+  }
+  if (urlStats && urlStats.freshness.stale + urlStats.freshness.old > entries.length * 0.3) {
+    recommendations.push("Review and update stale content (30%+ of URLs have old lastmod).");
+  }
+  for (const issue of validation.issues) {
+    recommendations.push(`Fix: ${issue.message}`);
+  }
+
+  return {
+    kind: "geo-sitemap",
+    source,
+    found: true,
+    isIndex,
+    childSitemaps,
+    entryCount: entries.length,
+    entries: entries.slice(0, options.maxEntries || 50),
+    urlStats,
+    validation,
+    score,
+    scoreLabel: score >= 80 ? "Good" : score >= 50 ? "Fair" : "Needs work",
+    recommendations,
+    summary: isIndex
+      ? `Sitemap index with ${childSitemaps.length} child sitemap(s).`
+      : `Sitemap with ${entries.length} URL(s). Score: ${score}/100. lastmod coverage: ${urlStats?.lastmodCoverage || 0}%.`
+  };
+}
+
+export function renderSitemapMarkdown(report) {
+  const lines = [
+    "# Sitemap Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Found: \`${report.found}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  if (!report.found) {
+    lines.push("## Action Required", "", "- Create and submit an XML sitemap.", "");
+    return lines.join("\n");
+  }
+
+  if (report.isIndex) {
+    lines.push("## Sitemap Index", "", `- Child sitemaps: \`${report.childSitemaps.length}\``, "");
+    for (const child of report.childSitemaps) {
+      lines.push(`- \`${child.loc}\`${child.lastmod ? ` (${child.lastmod})` : ""}`);
+    }
+    lines.push("");
+  } else if (report.urlStats) {
+    lines.push(
+      "## URL Statistics",
+      "",
+      `- Total URLs: \`${report.urlStats.total}\``,
+      `- With lastmod: \`${report.urlStats.withLastmod}\` (${report.urlStats.lastmodCoverage}%)`,
+      `- With changefreq: \`${report.urlStats.withChangefreq}\``,
+      `- With priority: \`${report.urlStats.withPriority}\``,
+      `- Average priority: \`${report.urlStats.avgPriority ?? "—"}\``,
+      `- Average URL depth: \`${report.urlStats.avgDepth}\``,
+      "",
+      "## Content Freshness",
+      "",
+      `- Fresh (< 30 days): \`${report.urlStats.freshness.fresh}\``,
+      `- Recent (30-180 days): \`${report.urlStats.freshness.recent}\``,
+      `- Stale (180-365 days): \`${report.urlStats.freshness.stale}\``,
+      `- Old (> 1 year): \`${report.urlStats.freshness.old}\``,
+      ""
+    );
+  }
+
+  if (report.validation.issues.length > 0 || report.validation.warnings.length > 0) {
+    lines.push("## Validation", "");
+    for (const issue of report.validation.issues) {
+      lines.push(`- ❌ ${issue.message}`);
+    }
+    for (const warning of report.validation.warnings) {
+      lines.push(`- ⚠️ ${warning.message}`);
+    }
+    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 writeSitemapOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/social-meta.js

@@ -0,0 +1,293 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+const OG_TAGS = [
+  { property: "og:title", required: true, label: "Title" },
+  { property: "og:description", required: true, label: "Description" },
+  { property: "og:image", required: true, label: "Image" },
+  { property: "og:url", required: true, label: "URL" },
+  { property: "og:type", required: false, label: "Type" },
+  { property: "og:site_name", required: false, label: "Site Name" },
+  { property: "og:locale", required: false, label: "Locale" },
+  { property: "og:image:width", required: false, label: "Image Width" },
+  { property: "og:image:height", required: false, label: "Image Height" },
+  { property: "og:image:alt", required: false, label: "Image Alt" }
+];
+
+const TWITTER_TAGS = [
+  { name: "twitter:card", required: true, label: "Card Type" },
+  { name: "twitter:title", required: false, label: "Title" },
+  { name: "twitter:description", required: false, label: "Description" },
+  { name: "twitter:image", required: false, label: "Image" },
+  { name: "twitter:site", required: false, label: "Site Handle" },
+  { name: "twitter:creator", required: false, label: "Creator Handle" },
+  { name: "twitter:image:alt", required: false, label: "Image Alt" }
+];
+
+function extractMetaTags(content) {
+  const tags = {};
+
+  // og: tags
+  const ogMatches = content.matchAll(/<meta[^>]+property=["'](og:[^"']+)["'][^>]+content=["']([^"']*)["']/gi);
+  for (const match of ogMatches) {
+    tags[match[1].toLowerCase()] = match[2].trim();
+  }
+
+  // Reverse order (content before property)
+  const ogReverseMatches = content.matchAll(/<meta[^>]+content=["']([^"']*)["'][^>]+property=["'](og:[^"']+)["']/gi);
+  for (const match of ogReverseMatches) {
+    const key = match[2].toLowerCase();
+    if (!tags[key]) tags[key] = match[1].trim();
+  }
+
+  // twitter: tags (both name= and property= variants)
+  const twitterMatches = content.matchAll(/<meta[^>]+(?:name|property)=["'](twitter:[^"']+)["'][^>]+content=["']([^"']*)["']/gi);
+  for (const match of twitterMatches) {
+    tags[match[1].toLowerCase()] = match[2].trim();
+  }
+
+  const twitterReverseMatches = content.matchAll(/<meta[^>]+content=["']([^"']*)["'][^>]+(?:name|property)=["'](twitter:[^"']+)["']/gi);
+  for (const match of twitterReverseMatches) {
+    const key = match[2].toLowerCase();
+    if (!tags[key]) tags[key] = match[1].trim();
+  }
+
+  return tags;
+}
+
+function validateOgTags(tags) {
+  const results = [];
+
+  for (const spec of OG_TAGS) {
+    const value = tags[spec.property];
+    const found = Boolean(value);
+
+    const issues = [];
+    if (spec.required && !found) {
+      issues.push({ severity: "error", message: `Missing required tag: ${spec.property}` });
+    }
+
+    if (found) {
+      if (spec.property === "og:title" && value.length > 60) {
+        issues.push({ severity: "warning", message: `og:title is long (${value.length} chars). Recommended: ≤ 60.` });
+      }
+      if (spec.property === "og:description" && value.length > 200) {
+        issues.push({ severity: "warning", message: `og:description is long (${value.length} chars). Recommended: ≤ 200.` });
+      }
+      if (spec.property === "og:image") {
+        if (!/^https:\/\//i.test(value)) {
+          issues.push({ severity: "warning", message: "og:image should use absolute HTTPS URL" });
+        }
+      }
+      if (spec.property === "og:url") {
+        try {
+          new URL(value);
+        } catch {
+          issues.push({ severity: "error", message: "og:url is not a valid URL" });
+        }
+      }
+    }
+
+    results.push({
+      tag: spec.property,
+      label: spec.label,
+      required: spec.required,
+      found,
+      value: value || null,
+      issues
+    });
+  }
+
+  return results;
+}
+
+function validateTwitterTags(tags) {
+  const results = [];
+
+  for (const spec of TWITTER_TAGS) {
+    const value = tags[spec.name];
+    const found = Boolean(value);
+
+    const issues = [];
+    if (spec.required && !found) {
+      issues.push({ severity: "error", message: `Missing required tag: ${spec.name}` });
+    }
+
+    if (found && spec.name === "twitter:card") {
+      const validTypes = ["summary", "summary_large_image", "app", "player"];
+      if (!validTypes.includes(value)) {
+        issues.push({ severity: "error", message: `Invalid twitter:card type: "${value}". Valid: ${validTypes.join(", ")}` });
+      }
+    }
+
+    results.push({
+      tag: spec.name,
+      label: spec.label,
+      required: spec.required,
+      found,
+      value: value || null,
+      issues
+    });
+  }
+
+  return results;
+}
+
+function computeScore(ogResults, twitterResults) {
+  const allResults = [...ogResults, ...twitterResults];
+  const required = allResults.filter((r) => r.required);
+  const requiredFound = required.filter((r) => r.found).length;
+  const optional = allResults.filter((r) => !r.required);
+  const optionalFound = optional.filter((r) => r.found).length;
+  const errors = allResults.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "error").length, 0);
+  const warnings = allResults.reduce((sum, r) => sum + r.issues.filter((i) => i.severity === "warning").length, 0);
+
+  let score = 0;
+  score += required.length > 0 ? Math.round((requiredFound / required.length) * 60) : 60;
+  score += optional.length > 0 ? Math.round((optionalFound / optional.length) * 25) : 25;
+  score += 15; // base
+  score -= errors * 8;
+  score -= warnings * 3;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function buildRecommendations(ogResults, twitterResults) {
+  const recs = [];
+
+  const missingRequired = [...ogResults, ...twitterResults]
+    .filter((r) => r.required && !r.found);
+
+  if (missingRequired.length > 0) {
+    recs.push(`Add missing required tags: ${missingRequired.map((r) => r.tag).join(", ")}`);
+  }
+
+  const ogImage = ogResults.find((r) => r.tag === "og:image");
+  if (ogImage && !ogImage.found && !missingRequired.some((r) => r.tag === "og:image")) {
+    recs.push("Add og:image. Shared links with images get 2-3x more engagement.");
+  }
+
+  const imageAlt = ogResults.find((r) => r.tag === "og:image:alt");
+  if (ogImage?.found && !imageAlt?.found) {
+    recs.push("Add og:image:alt for accessibility and better AI understanding of the image.");
+  }
+
+  const imageDims = ogResults.filter((r) => r.tag.includes("image:width") || r.tag.includes("image:height"));
+  if (ogImage?.found && imageDims.every((r) => !r.found)) {
+    recs.push("Add og:image:width and og:image:height to prevent layout shift on social platforms.");
+  }
+
+  const twitterCard = twitterResults.find((r) => r.tag === "twitter:card");
+  if (!twitterCard?.found) {
+    recs.push("Add twitter:card (summary_large_image recommended for articles).");
+  }
+
+  return recs;
+}
+
+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 analyzeSocialMeta(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 tags = extractMetaTags(content);
+  const ogResults = validateOgTags(tags);
+  const twitterResults = validateTwitterTags(tags);
+  const score = computeScore(ogResults, twitterResults);
+  const recommendations = buildRecommendations(ogResults, twitterResults);
+
+  const ogFound = ogResults.filter((r) => r.found).length;
+  const twitterFound = twitterResults.filter((r) => r.found).length;
+
+  return {
+    kind: "geo-social-meta",
+    source,
+    openGraph: {
+      found: ogFound,
+      total: ogResults.length,
+      tags: ogResults
+    },
+    twitter: {
+      found: twitterFound,
+      total: twitterResults.length,
+      tags: twitterResults
+    },
+    score,
+    scoreLabel: score >= 80 ? "Good" : score >= 50 ? "Fair" : "Needs work",
+    recommendations,
+    summary: `Social meta: ${score}/100. OG tags: ${ogFound}/${ogResults.length}. Twitter tags: ${twitterFound}/${twitterResults.length}.`
+  };
+}
+
+export function renderSocialMetaMarkdown(report) {
+  const lines = [
+    "# Social Meta Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Open Graph Tags",
+    "",
+    "| Tag | Status | Value |",
+    "|-----|--------|-------|"
+  ];
+
+  for (const tag of report.openGraph.tags) {
+    const icon = tag.found ? "✅" : (tag.required ? "❌" : "—");
+    const value = tag.value ? tag.value.slice(0, 60) + (tag.value.length > 60 ? "..." : "") : "";
+    lines.push(`| ${tag.tag} | ${icon} | ${value} |`);
+  }
+
+  lines.push("", "## Twitter Card Tags", "", "| Tag | Status | Value |", "|-----|--------|-------|");
+
+  for (const tag of report.twitter.tags) {
+    const icon = tag.found ? "✅" : (tag.required ? "❌" : "—");
+    const value = tag.value ? tag.value.slice(0, 60) + (tag.value.length > 60 ? "..." : "") : "";
+    lines.push(`| ${tag.tag} | ${icon} | ${value} |`);
+  }
+
+  const allIssues = [...report.openGraph.tags, ...report.twitter.tags].flatMap((t) => t.issues);
+  if (allIssues.length > 0) {
+    lines.push("", "## Issues", "");
+    for (const issue of allIssues) {
+      const icon = issue.severity === "error" ? "❌" : "⚠️";
+      lines.push(`- ${icon} ${issue.message}`);
+    }
+  }
+
+  lines.push("", "## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Social meta tags are well-configured.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeSocialMetaOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}