geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/internal-links.js

@@ -0,0 +1,298 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+function extractLinks(content, baseUrl) {
+  const links = [];
+  let base;
+  try {
+    base = new URL(baseUrl || "https://example.com");
+  } catch {
+    base = new URL("https://example.com");
+  }
+
+  // HTML links
+  const htmlMatches = content.matchAll(/<a\s[^>]*href=["']([^"'#]+)["'][^>]*>([\s\S]*?)<\/a>/gi);
+  for (const match of htmlMatches) {
+    const href = match[1].trim();
+    const anchorText = match[2].replace(/<[^>]+>/g, "").trim();
+    links.push({ href, anchorText, source: "html" });
+  }
+
+  // Markdown links
+  const mdMatches = content.matchAll(/\[([^\]]+)\]\(([^)#]+)\)/g);
+  for (const match of mdMatches) {
+    links.push({ href: match[2].trim(), anchorText: match[1].trim(), source: "markdown" });
+  }
+
+  const internal = [];
+  const external = [];
+
+  for (const link of links) {
+    try {
+      const resolved = new URL(link.href, base);
+      const isInternal = resolved.hostname === base.hostname || link.href.startsWith("/") || link.href.startsWith("./");
+
+      if (isInternal) {
+        internal.push({
+          url: resolved.pathname,
+          fullUrl: resolved.href,
+          anchorText: link.anchorText,
+          source: link.source
+        });
+      } else {
+        external.push({
+          url: resolved.href,
+          anchorText: link.anchorText,
+          source: link.source
+        });
+      }
+    } catch {
+      if (link.href.startsWith("/") || link.href.startsWith("./")) {
+        internal.push({
+          url: link.href,
+          fullUrl: link.href,
+          anchorText: link.anchorText,
+          source: link.source
+        });
+      }
+    }
+  }
+
+  return { internal, external };
+}
+
+function analyzeAnchorText(links) {
+  const issues = [];
+  const generic = ["click here", "read more", "learn more", "here", "link", "this", "more", "see more"];
+  const genericLinks = links.filter((l) => generic.includes(l.anchorText.toLowerCase()));
+  const emptyLinks = links.filter((l) => !l.anchorText || l.anchorText.length === 0);
+  const longLinks = links.filter((l) => l.anchorText.length > 60);
+
+  if (genericLinks.length > 0) {
+    issues.push({
+      severity: "warning",
+      message: `${genericLinks.length} link(s) use generic anchor text: ${genericLinks.slice(0, 3).map((l) => `"${l.anchorText}"`).join(", ")}`,
+      count: genericLinks.length
+    });
+  }
+
+  if (emptyLinks.length > 0) {
+    issues.push({
+      severity: "error",
+      message: `${emptyLinks.length} link(s) have empty anchor text`,
+      count: emptyLinks.length
+    });
+  }
+
+  if (longLinks.length > 0) {
+    issues.push({
+      severity: "info",
+      message: `${longLinks.length} link(s) have very long anchor text (> 60 chars)`,
+      count: longLinks.length
+    });
+  }
+
+  const descriptive = links.filter((l) =>
+    l.anchorText.length >= 3 &&
+    l.anchorText.length <= 60 &&
+    !generic.includes(l.anchorText.toLowerCase())
+  );
+
+  return {
+    total: links.length,
+    descriptive: descriptive.length,
+    generic: genericLinks.length,
+    empty: emptyLinks.length,
+    qualityRatio: links.length > 0 ? Math.round((descriptive.length / links.length) * 100) : 100,
+    issues
+  };
+}
+
+function analyzeInternalPaths(internalLinks) {
+  const pathCounts = {};
+  for (const link of internalLinks) {
+    const p = link.url.split("?")[0].split("#")[0];
+    pathCounts[p] = (pathCounts[p] || 0) + 1;
+  }
+
+  const uniquePaths = Object.keys(pathCounts);
+  const mostLinked = Object.entries(pathCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([url, count]) => ({ url, count }));
+
+  const depths = uniquePaths.map((p) => p.split("/").filter(Boolean).length);
+  const avgDepth = depths.length > 0 ? Math.round((depths.reduce((a, b) => a + b, 0) / depths.length) * 10) / 10 : 0;
+  const maxDepth = depths.length > 0 ? Math.max(...depths) : 0;
+
+  return {
+    uniquePaths: uniquePaths.length,
+    totalLinks: internalLinks.length,
+    avgDepth,
+    maxDepth,
+    mostLinked,
+    duplicateLinks: internalLinks.length - uniquePaths.length
+  };
+}
+
+function computeScore(internalLinks, externalLinks, anchorAnalysis, pathAnalysis) {
+  let score = 0;
+
+  // Internal link presence
+  score += Math.min(internalLinks.length * 5, 25);
+
+  // External link presence (citations)
+  score += Math.min(externalLinks.length * 3, 15);
+
+  // Anchor text quality
+  score += Math.round(anchorAnalysis.qualityRatio * 0.3);
+
+  // Unique path coverage
+  score += Math.min(pathAnalysis.uniquePaths * 3, 15);
+
+  // Penalties
+  score -= anchorAnalysis.empty * 5;
+  score -= anchorAnalysis.generic * 2;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function buildRecommendations(internalLinks, externalLinks, anchorAnalysis, pathAnalysis) {
+  const recs = [];
+
+  if (internalLinks.length === 0) {
+    recs.push("Add internal links to connect related content and help AI understand site structure.");
+  } else if (internalLinks.length < 3) {
+    recs.push("Add more internal links (aim for 3-5 per page) to improve content discovery.");
+  }
+
+  if (externalLinks.length === 0) {
+    recs.push("Add external source links to increase content credibility and citability.");
+  }
+
+  for (const issue of anchorAnalysis.issues) {
+    if (issue.severity === "error" || issue.severity === "warning") {
+      recs.push(issue.message.charAt(0).toUpperCase() + issue.message.slice(1) + ". Use descriptive anchor text instead.");
+    }
+  }
+
+  if (pathAnalysis.maxDepth > 4) {
+    recs.push(`Some linked pages are ${pathAnalysis.maxDepth} levels deep. Flatten URL structure for better crawlability.`);
+  }
+
+  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 analyzeInternalLinks(input, options = {}) {
+  let content;
+  let source;
+  let baseUrl = options.baseUrl;
+
+  if (/^https?:\/\//i.test(input)) {
+    content = await fetchContent(input);
+    source = input;
+    baseUrl = baseUrl || input;
+  } else {
+    const filePath = path.resolve(input);
+    content = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  const { internal, external } = extractLinks(content, baseUrl);
+  const anchorAnalysis = analyzeAnchorText([...internal, ...external]);
+  const internalAnchorAnalysis = analyzeAnchorText(internal);
+  const pathAnalysis = analyzeInternalPaths(internal);
+  const score = computeScore(internal, external, anchorAnalysis, pathAnalysis);
+  const recommendations = buildRecommendations(internal, external, anchorAnalysis, pathAnalysis);
+
+  return {
+    kind: "geo-internal-links",
+    source,
+    internalLinks: {
+      total: internal.length,
+      unique: pathAnalysis.uniquePaths,
+      anchorQuality: internalAnchorAnalysis.qualityRatio,
+      mostLinked: pathAnalysis.mostLinked,
+      avgDepth: pathAnalysis.avgDepth,
+      maxDepth: pathAnalysis.maxDepth
+    },
+    externalLinks: {
+      total: external.length,
+      domains: [...new Set(external.map((l) => {
+        try { return new URL(l.url).hostname; } catch { return l.url; }
+      }))].slice(0, 20)
+    },
+    anchorAnalysis,
+    score,
+    scoreLabel: score >= 70 ? "Good" : score >= 40 ? "Fair" : "Needs work",
+    recommendations,
+    summary: `${internal.length} internal, ${external.length} external links. Anchor quality: ${anchorAnalysis.qualityRatio}%.`
+  };
+}
+
+export function renderInternalLinksMarkdown(report) {
+  const lines = [
+    "# Internal Link Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Internal Links",
+    "",
+    `- Total: \`${report.internalLinks.total}\``,
+    `- Unique paths: \`${report.internalLinks.unique}\``,
+    `- Anchor text quality: \`${report.internalLinks.anchorQuality}%\``,
+    `- Average link depth: \`${report.internalLinks.avgDepth}\``,
+    "",
+    "## External Links",
+    "",
+    `- Total: \`${report.externalLinks.total}\``,
+    `- Unique domains: ${report.externalLinks.domains.slice(0, 10).map((d) => `\`${d}\``).join(", ") || "none"}`,
+    ""
+  ];
+
+  if (report.internalLinks.mostLinked.length > 0) {
+    lines.push("## Most Linked Internal Paths", "");
+    for (const item of report.internalLinks.mostLinked) {
+      lines.push(`- \`${item.url}\` (${item.count}x)`);
+    }
+    lines.push("");
+  }
+
+  if (report.anchorAnalysis.issues.length > 0) {
+    lines.push("## Anchor Text Issues", "");
+    for (const issue of report.anchorAnalysis.issues) {
+      const icon = issue.severity === "error" ? "❌" : issue.severity === "warning" ? "⚠️" : "ℹ️";
+      lines.push(`- ${icon} ${issue.message}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Link structure is well-optimized.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeInternalLinksOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/page-audit.js

@@ -15,7 +15,7 @@ async function fetchText(url) {
   const response = await fetch(url, {
     redirect: "follow",
     headers: {
-      "user-agent": "geo-ai-search-optimization/1.4.0"
+      "user-agent": "geo-ai-search-optimization/2.2.0"
     }
   });
 

package/src/page-snapshot.js

@@ -0,0 +1,198 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+const DEFAULT_DATA_DIR = ".geo-data/page-snapshots";
+
+function sanitizeKey(input) {
+  return input
+    .replace(/^https?:\/\//, "")
+    .replace(/[^a-zA-Z0-9.-]/g, "_")
+    .replace(/_+/g, "_")
+    .slice(0, 120);
+}
+
+export async function savePageSnapshot(pageAuditResult, options = {}) {
+  const dataDir = path.resolve(options.dataDir || DEFAULT_DATA_DIR);
+  await fs.mkdir(dataDir, { recursive: true });
+
+  const key = sanitizeKey(pageAuditResult.input || pageAuditResult.source || "unknown");
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const filename = `${key}__${timestamp}.json`;
+  const filePath = path.join(dataDir, filename);
+
+  const snapshot = {
+    timestamp: new Date().toISOString(),
+    input: pageAuditResult.input,
+    source: pageAuditResult.source,
+    kind: pageAuditResult.kind,
+    compositeScore: pageAuditResult.compositeScore,
+    dimensions: pageAuditResult.dimensions
+      ? Object.fromEntries(
+          Object.entries(pageAuditResult.dimensions).map(([k, v]) => [k, { score: v.score, label: v.label }])
+        )
+      : { base: { score: pageAuditResult.score?.score ?? pageAuditResult.score ?? 0 } }
+  };
+
+  await fs.writeFile(filePath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+  return { path: filePath, key, snapshot };
+}
+
+export async function listPageSnapshots(input, options = {}) {
+  const dataDir = path.resolve(options.dataDir || DEFAULT_DATA_DIR);
+  const key = sanitizeKey(input);
+
+  let files;
+  try {
+    files = await fs.readdir(dataDir);
+  } catch {
+    return [];
+  }
+
+  return files
+    .filter((f) => f.startsWith(`${key}__`) && f.endsWith(".json"))
+    .sort()
+    .reverse();
+}
+
+export async function loadPageSnapshot(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  return JSON.parse(content);
+}
+
+export async function buildPageTrend(input, options = {}) {
+  const dataDir = path.resolve(options.dataDir || DEFAULT_DATA_DIR);
+  const key = sanitizeKey(input);
+  const files = await listPageSnapshots(input, options);
+  const last = options.last || 0;
+  const selectedFiles = last > 0 ? files.slice(0, last) : files;
+
+  if (selectedFiles.length === 0) {
+    return {
+      kind: "geo-page-trend",
+      input,
+      key,
+      snapshotCount: 0,
+      snapshots: [],
+      trend: null,
+      summary: `No snapshots found for ${input}. Run full-page-audit --save first.`
+    };
+  }
+
+  const snapshots = [];
+  for (const file of selectedFiles) {
+    try {
+      const data = await loadPageSnapshot(path.join(dataDir, file));
+      snapshots.push(data);
+    } catch {
+      // Skip corrupt snapshots
+    }
+  }
+
+  // Reverse to chronological order
+  snapshots.reverse();
+
+  // Compute trend
+  let trend = null;
+  if (snapshots.length >= 2) {
+    const first = snapshots[0];
+    const latest = snapshots[snapshots.length - 1];
+    const firstScore = first.compositeScore ?? first.dimensions?.base?.score ?? 0;
+    const latestScore = latest.compositeScore ?? latest.dimensions?.base?.score ?? 0;
+    const delta = latestScore - firstScore;
+
+    // Per-dimension trends
+    const dimensionTrends = {};
+    const allDimKeys = new Set([
+      ...Object.keys(first.dimensions || {}),
+      ...Object.keys(latest.dimensions || {})
+    ]);
+
+    for (const dimKey of allDimKeys) {
+      const firstDim = first.dimensions?.[dimKey]?.score ?? 0;
+      const latestDim = latest.dimensions?.[dimKey]?.score ?? 0;
+      dimensionTrends[dimKey] = {
+        first: firstDim,
+        latest: latestDim,
+        delta: latestDim - firstDim,
+        direction: latestDim > firstDim ? "up" : latestDim < firstDim ? "down" : "flat"
+      };
+    }
+
+    trend = {
+      firstDate: first.timestamp,
+      latestDate: latest.timestamp,
+      firstScore,
+      latestScore,
+      delta,
+      direction: delta > 0 ? "improving" : delta < 0 ? "declining" : "stable",
+      dimensionTrends
+    };
+  }
+
+  return {
+    kind: "geo-page-trend",
+    input,
+    key,
+    snapshotCount: snapshots.length,
+    snapshots: snapshots.map((s) => ({
+      timestamp: s.timestamp,
+      compositeScore: s.compositeScore ?? s.dimensions?.base?.score ?? 0
+    })),
+    trend,
+    summary: trend
+      ? `${snapshots.length} snapshots. Score: ${trend.firstScore} → ${trend.latestScore} (${trend.delta >= 0 ? "+" : ""}${trend.delta}). Trend: ${trend.direction}.`
+      : `${snapshots.length} snapshot(s) for ${input}.`
+  };
+}
+
+export function renderPageTrendMarkdown(report) {
+  const lines = [
+    "# Page Trend Analysis",
+    "",
+    `- Input: \`${report.input}\``,
+    `- Snapshots: \`${report.snapshotCount}\``,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  if (report.snapshotCount === 0) {
+    lines.push("No snapshots found. Run `full-page-audit <url> --save` to start tracking.", "");
+    return lines.join("\n");
+  }
+
+  if (report.trend) {
+    const arrow = report.trend.direction === "improving" ? "📈" : report.trend.direction === "declining" ? "📉" : "➡️";
+    lines.push(
+      "## Overall Trend",
+      "",
+      `- ${arrow} **${report.trend.firstScore} → ${report.trend.latestScore}** (${report.trend.delta >= 0 ? "+" : ""}${report.trend.delta})`,
+      `- Direction: **${report.trend.direction}**`,
+      `- Period: ${report.trend.firstDate.slice(0, 10)} → ${report.trend.latestDate.slice(0, 10)}`,
+      ""
+    );
+
+    if (report.trend.dimensionTrends) {
+      lines.push("## Dimension Trends", "", "| Dimension | First | Latest | Delta | Direction |", "|-----------|-------|--------|-------|-----------|");
+      for (const [dim, t] of Object.entries(report.trend.dimensionTrends)) {
+        const icon = t.direction === "up" ? "📈" : t.direction === "down" ? "📉" : "➡️";
+        lines.push(`| ${dim} | ${t.first} | ${t.latest} | ${t.delta >= 0 ? "+" : ""}${t.delta} | ${icon} ${t.direction} |`);
+      }
+      lines.push("");
+    }
+  }
+
+  if (report.snapshots.length > 0) {
+    lines.push("## Snapshot History", "");
+    for (const s of report.snapshots) {
+      lines.push(`- \`${s.timestamp.slice(0, 19)}\` — Score: **${s.compositeScore}**`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export async function writePageTrendOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}