geo-ai-search-optimization 2.5.0 → 2.6.0

package/README.md

@@ -193,7 +193,7 @@ Full TypeScript declarations included (`index.d.ts`) — 230+ exports with IDE a
 ## GitHub Action
 
 ```yaml
-- uses: redredchen01/geo-ai-search-optimization@v2.5.0
+- uses: redredchen01/geo-ai-search-optimization@v2.6.0
   with:
     project-path: ./your-project
     min-score: 60

package/action.yml

@@ -51,7 +51,7 @@ runs:
 
     - name: Install geo-ai-search-optimization
       shell: bash
-      run: npm install -g geo-ai-search-optimization@2.5.0
+      run: npm install -g geo-ai-search-optimization@2.6.0
 
     - name: Run GEO Audit
       id: audit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geo-ai-search-optimization",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Install and run a Generative Engine Optimization (GEO)-first, SEO-supported Codex skill for website optimization.",
   "type": "module",
   "bin": {

package/src/ai-snippet-simulator.js

@@ -0,0 +1,359 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fetchText } from "./fetch-utils.js";
+import { writeScanOutput } from "./scan.js";
+
+function stripHtml(text) {
+  return text
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<nav[\s\S]*?<\/nav>/gi, " ")
+    .replace(/<footer[\s\S]*?<\/footer>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&[a-z0-9#]+;/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function extractPlainText(content) {
+  if (/<html|<head|<body/i.test(content)) {
+    return stripHtml(content);
+  }
+  return content.replace(/^---[\s\S]*?---/, "").trim();
+}
+
+/**
+ * Extract headings and their positions so we can detect "follows a heading".
+ */
+function extractHeadingPositions(content) {
+  const positions = [];
+  const regex = /<h[1-6][^>]*>([\s\S]*?)<\/h[1-6]>/gi;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    positions.push(match.index);
+  }
+  // Also match markdown headings
+  const mdRegex = /^#{1,6}\s+.+$/gm;
+  while ((match = mdRegex.exec(content)) !== null) {
+    positions.push(match.index);
+  }
+  return positions;
+}
+
+function splitSentences(text) {
+  return text
+    .split(/(?<=[.!?])\s+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 10);
+}
+
+const NUMBER_STAT_PATTERN = /\b\d+(\.\d+)?\s*(%|percent|million|billion|thousand|x|times|fold)\b/i;
+const NUMBER_PATTERN = /\b\d{2,}(\.\d+)?\b/;
+const DATE_PATTERN = /\b(20[12]\d|19\d\d)\b/;
+const DEFINITIVE_PATTERN = /\b(is|are|was|were|means?|refers? to|defined as|according to|known as)\b/i;
+const SELF_CONTAINED_PATTERN = /^[A-Z][A-Za-z]+\s+(is|are|was|were|has|have|had|can|could|will|would|should|must|means?)\b/;
+const PROPER_NOUN_PATTERN = /\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b/;
+const NAV_JUNK_PATTERN = /\b(click here|read more|learn more|sign up|subscribe|menu|navigation|skip to|cookie|privacy policy)\b/i;
+
+function scoreSentence(sentence, index, totalSentences, followsHeading) {
+  let score = 0;
+  const reasons = [];
+  const wordCount = sentence.split(/\s+/).length;
+
+  // +25 if contains number/stat/percentage
+  if (NUMBER_STAT_PATTERN.test(sentence) || (NUMBER_PATTERN.test(sentence) && DATE_PATTERN.test(sentence))) {
+    score += 25;
+    reasons.push("contains numbers/stats");
+  }
+
+  // +20 if self-contained (starts with subject, has verb)
+  if (SELF_CONTAINED_PATTERN.test(sentence)) {
+    score += 20;
+    reasons.push("self-contained");
+  }
+
+  // +15 if uses definitive language
+  if (DEFINITIVE_PATTERN.test(sentence)) {
+    score += 15;
+    reasons.push("definitive language");
+  }
+
+  // +15 if length 20-60 words (optimal snippet length)
+  if (wordCount >= 20 && wordCount <= 60) {
+    score += 15;
+    reasons.push("optimal length");
+  }
+
+  // +10 if in first 30% of content
+  if (totalSentences > 0 && index / totalSentences < 0.3) {
+    score += 10;
+    reasons.push("early position");
+  }
+
+  // +10 if follows a heading
+  if (followsHeading) {
+    score += 10;
+    reasons.push("follows heading");
+  }
+
+  // +5 if contains a proper noun
+  if (PROPER_NOUN_PATTERN.test(sentence)) {
+    score += 5;
+    reasons.push("proper noun");
+  }
+
+  // -20 if contains navigation text
+  if (NAV_JUNK_PATTERN.test(sentence)) {
+    score -= 20;
+    reasons.push("navigation/junk text");
+  }
+
+  return { score: Math.max(0, Math.min(100, score)), reasons };
+}
+
+function buildFollowsHeadingMap(plainText, sentences, rawContent) {
+  const headingPositions = extractHeadingPositions(rawContent);
+  const map = new Map();
+
+  for (let i = 0; i < sentences.length; i++) {
+    const sentencePos = plainText.indexOf(sentences[i]);
+    let follows = false;
+    // Check if any heading appears shortly before this sentence in raw content
+    // Simplified: first sentence and sentences right after a heading-like pattern
+    if (i === 0) {
+      follows = true;
+    } else {
+      const prevSentence = sentences[i - 1];
+      // If previous text ends near a heading boundary, mark as follows heading
+      if (headingPositions.length > 0) {
+        follows = i <= headingPositions.length;
+      }
+    }
+    map.set(i, follows);
+  }
+
+  return map;
+}
+
+function generateSimulatedSnippets(topQuotables, source) {
+  const bestSentence = topQuotables[0]?.sentence || "No quotable content found.";
+  const secondBest = topQuotables[1]?.sentence || bestSentence;
+  const domain = extractDomain(source);
+
+  return {
+    chatgpt: {
+      snippet: `According to ${domain}, ${lowerFirst(bestSentence)} ${secondBest.length < 200 ? secondBest : ""}`.trim(),
+      citation: `Source: ${source}`
+    },
+    perplexity: {
+      snippet: `"${bestSentence}" [1]`,
+      citation: `[1] ${source}`
+    },
+    googleAio: {
+      snippet: `${bestSentence} ${topQuotables[2]?.sentence || ""}`.trim(),
+      citation: source
+    },
+    gemini: {
+      snippet: bestSentence,
+      citation: `Based on information from ${domain}`
+    }
+  };
+}
+
+function extractDomain(source) {
+  try {
+    return new URL(source).hostname;
+  } catch {
+    return path.basename(source);
+  }
+}
+
+function lowerFirst(str) {
+  if (!str) return str;
+  // Don't lowercase if starts with proper noun or acronym
+  if (/^[A-Z]{2,}/.test(str) || /^[A-Z][a-z]+\s+[A-Z]/.test(str)) return str;
+  return str[0].toLowerCase() + str.slice(1);
+}
+
+function getScoreLabel(score) {
+  if (score >= 80) return "Highly Quotable";
+  if (score >= 60) return "Quotable";
+  if (score >= 40) return "Partially Quotable";
+  return "Low Quotability";
+}
+
+function buildRecommendations(topQuotables, sentences, score) {
+  const recs = [];
+  const avgScore = topQuotables.length > 0
+    ? Math.round(topQuotables.reduce((s, q) => s + q.score, 0) / topQuotables.length)
+    : 0;
+
+  if (topQuotables.length < 3) {
+    recs.push("Add more self-contained, factual sentences that AI engines can directly quote.");
+  }
+  if (avgScore < 40) {
+    recs.push("Strengthen sentences with specific numbers, statistics, or data points.");
+  }
+
+  const hasDefinitive = topQuotables.some((q) => q.reason.includes("definitive language"));
+  if (!hasDefinitive) {
+    recs.push("Use definitive language patterns like 'X is...', 'X means...', 'According to...' for clearer AI extraction.");
+  }
+
+  const hasOptimalLength = topQuotables.some((q) => q.reason.includes("optimal length"));
+  if (!hasOptimalLength) {
+    recs.push("Write key sentences in the 20-60 word range for optimal AI snippet length.");
+  }
+
+  const hasNumbers = topQuotables.some((q) => q.reason.includes("numbers/stats"));
+  if (!hasNumbers) {
+    recs.push("Include specific numbers, percentages, or statistics to increase citation likelihood.");
+  }
+
+  if (sentences.length < 10) {
+    recs.push("Expand content with more informative sentences to give AI engines more material to cite.");
+  }
+
+  const earlyQuotables = topQuotables.filter((q) => q.reason.includes("early position"));
+  if (earlyQuotables.length === 0 && topQuotables.length > 0) {
+    recs.push("Move your strongest factual claims earlier in the content for position bias advantage.");
+  }
+
+  return recs;
+}
+
+export async function simulateAiSnippet(input, options = {}) {
+  let rawContent;
+  let source;
+
+  if (/^https?:\/\//i.test(input)) {
+    rawContent = await fetchText(input);
+    source = input;
+  } else {
+    const filePath = path.resolve(input);
+    rawContent = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  const plainText = extractPlainText(rawContent);
+  const sentences = splitSentences(plainText);
+  const followsHeadingMap = buildFollowsHeadingMap(plainText, sentences, rawContent);
+
+  // Score all sentences
+  const scored = sentences.map((sentence, index) => {
+    const { score, reasons } = scoreSentence(
+      sentence,
+      index,
+      sentences.length,
+      followsHeadingMap.get(index) || false
+    );
+    return {
+      sentence: sentence.slice(0, 300),
+      score,
+      reason: reasons.join(", ") || "baseline",
+      position: index
+    };
+  });
+
+  // Sort by score descending, take top quotables
+  const topQuotables = scored
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 10);
+
+  // Generate simulated snippets
+  const simulatedSnippets = generateSimulatedSnippets(topQuotables, source);
+
+  // Snippet readiness
+  const top5 = topQuotables.slice(0, 5);
+  const avgScore = top5.length > 0
+    ? Math.round(top5.reduce((s, q) => s + q.score, 0) / top5.length)
+    : 0;
+  const topScore = top5.length > 0 ? top5[0].score : 0;
+
+  const overallScore = Math.round(Math.min(avgScore, 100));
+  const scoreLabel = getScoreLabel(overallScore);
+  const recommendations = buildRecommendations(topQuotables, sentences, overallScore);
+
+  return {
+    kind: "geo-ai-snippet-simulator",
+    source,
+    topQuotables,
+    simulatedSnippets,
+    snippetReadiness: {
+      quotableSentences: topQuotables.length,
+      avgScore,
+      topScore
+    },
+    recommendations,
+    score: overallScore,
+    scoreLabel,
+    summary: `Snippet readiness: ${overallScore}/100 (${scoreLabel}). ${topQuotables.length} quotable sentences found. ${recommendations[0] || "Content is well-optimized for AI snippet extraction."}`
+  };
+}
+
+export function renderAiSnippetMarkdown(report) {
+  const lines = [
+    "# AI Snippet Simulator",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Snippet Readiness Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Quotable Sentences: \`${report.snippetReadiness.quotableSentences}\``,
+    `- Average Score (top 5): \`${report.snippetReadiness.avgScore}\``,
+    `- Top Score: \`${report.snippetReadiness.topScore}\``,
+    "",
+    "## Simulated AI Snippets",
+    "",
+    "### ChatGPT Style",
+    "",
+    `> ${report.simulatedSnippets.chatgpt.snippet}`,
+    "",
+    `*${report.simulatedSnippets.chatgpt.citation}*`,
+    "",
+    "### Perplexity Style",
+    "",
+    `> ${report.simulatedSnippets.perplexity.snippet}`,
+    "",
+    `*${report.simulatedSnippets.perplexity.citation}*`,
+    "",
+    "### Google AI Overviews Style",
+    "",
+    `> ${report.simulatedSnippets.googleAio.snippet}`,
+    "",
+    `*${report.simulatedSnippets.googleAio.citation}*`,
+    "",
+    "### Gemini Style",
+    "",
+    `> ${report.simulatedSnippets.gemini.snippet}`,
+    "",
+    `*${report.simulatedSnippets.gemini.citation}*`,
+    "",
+    "## Top Quotable Sentences",
+    ""
+  ];
+
+  if (report.topQuotables.length === 0) {
+    lines.push("- No highly quotable sentences detected.");
+  } else {
+    for (const q of report.topQuotables) {
+      lines.push(`- (score ${q.score}, pos ${q.position}) ${q.sentence}`);
+      lines.push(`  *Reason: ${q.reason}*`);
+    }
+  }
+
+  lines.push("", "## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Content is well-optimized for AI snippet extraction.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+export async function writeAiSnippetOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}