geo-ai-search-optimization 2.5.0 → 2.7.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.7.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.7.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.7.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);
+}

package/src/alert-rules.js

@@ -0,0 +1,248 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+const DEFAULT_RULES = [
+  { name: "Low Score", condition: "score-below", threshold: 40, action: "console" },
+  { name: "Score Drop", condition: "score-drop", threshold: 10, action: "console" },
+  { name: "Weak Citability", condition: "dimension-below", threshold: 30, dimension: "citability", action: "console" }
+];
+
+/**
+ * Create an alert rule evaluator from a rules array.
+ */
+export function createAlertRules(rules) {
+  const effectiveRules = rules && rules.length > 0 ? rules : DEFAULT_RULES;
+  return {
+    evaluate(auditResult, previousResult) {
+      return evaluateAlertRules(effectiveRules, auditResult, { previousResult });
+    }
+  };
+}
+
+/**
+ * Evaluate alert rules against an audit result.
+ */
+export async function evaluateAlertRules(rules, auditResult, options = {}) {
+  const effectiveRules = rules && rules.length > 0 ? rules : DEFAULT_RULES;
+  const { previousResult, competitorScores } = options;
+  const score = auditResult.compositeScore ?? auditResult.score ?? 0;
+  const dimensions = auditResult.dimensions ?? {};
+
+  const triggered = [];
+  const passed = [];
+
+  for (const rule of effectiveRules) {
+    const result = evaluateSingleRule(rule, score, dimensions, previousResult, competitorScores);
+    if (result.triggered) {
+      triggered.push(result.detail);
+    } else {
+      passed.push({ rule: rule.name });
+    }
+  }
+
+  // Execute actions for triggered alerts
+  for (const alert of triggered) {
+    try {
+      await executeAction(alert, rules.find((r) => r.name === alert.rule));
+      alert.actionExecuted = true;
+    } catch {
+      alert.actionExecuted = false;
+    }
+  }
+
+  const summary = triggered.length === 0
+    ? `All ${effectiveRules.length} rules passed. Score: ${score}/100.`
+    : `${triggered.length}/${effectiveRules.length} rules triggered. Score: ${score}/100. Alerts: ${triggered.map((t) => t.rule).join(", ")}.`;
+
+  return {
+    kind: "geo-alert-rules",
+    rulesEvaluated: effectiveRules.length,
+    triggered,
+    passed,
+    score,
+    summary
+  };
+}
+
+function evaluateSingleRule(rule, score, dimensions, previousResult, competitorScores) {
+  switch (rule.condition) {
+    case "score-below": {
+      if (score < rule.threshold) {
+        return {
+          triggered: true,
+          detail: {
+            rule: rule.name,
+            condition: rule.condition,
+            message: `Composite score ${score} is below threshold ${rule.threshold}.`,
+            value: score,
+            threshold: rule.threshold,
+            actionExecuted: false
+          }
+        };
+      }
+      return { triggered: false };
+    }
+
+    case "score-drop": {
+      if (!previousResult) return { triggered: false };
+      const prevScore = previousResult.compositeScore ?? previousResult.score ?? 0;
+      const drop = prevScore - score;
+      if (drop > rule.threshold) {
+        return {
+          triggered: true,
+          detail: {
+            rule: rule.name,
+            condition: rule.condition,
+            message: `Score dropped by ${drop} points (${prevScore} → ${score}), exceeding threshold of ${rule.threshold}.`,
+            value: drop,
+            threshold: rule.threshold,
+            actionExecuted: false
+          }
+        };
+      }
+      return { triggered: false };
+    }
+
+    case "dimension-below": {
+      const dim = rule.dimension;
+      if (!dim || !dimensions[dim]) return { triggered: false };
+      const dimScore = typeof dimensions[dim] === "object" ? dimensions[dim].score : dimensions[dim];
+      if (dimScore < rule.threshold) {
+        return {
+          triggered: true,
+          detail: {
+            rule: rule.name,
+            condition: rule.condition,
+            message: `Dimension "${dim}" score ${dimScore} is below threshold ${rule.threshold}.`,
+            value: dimScore,
+            threshold: rule.threshold,
+            actionExecuted: false
+          }
+        };
+      }
+      return { triggered: false };
+    }
+
+    case "competitor-overtake": {
+      if (!competitorScores || competitorScores.length === 0) return { triggered: false };
+      const overtaking = competitorScores.filter((c) => c.score > score);
+      if (overtaking.length > 0) {
+        const top = overtaking.reduce((a, b) => (a.score > b.score ? a : b));
+        return {
+          triggered: true,
+          detail: {
+            rule: rule.name,
+            condition: rule.condition,
+            message: `Competitor "${top.url || top.name || "unknown"}" (${top.score}) overtook own score (${score}).`,
+            value: top.score,
+            threshold: score,
+            actionExecuted: false
+          }
+        };
+      }
+      return { triggered: false };
+    }
+
+    default:
+      return { triggered: false };
+  }
+}
+
+async function executeAction(alert, rule) {
+  if (!rule) return;
+
+  switch (rule.action) {
+    case "console": {
+      const line = `[ALERT] ${alert.rule}: ${alert.message}`;
+      process.stdout.write(line + "\n");
+      break;
+    }
+
+    case "webhook": {
+      const url = rule.actionConfig?.url;
+      if (!url) throw new Error("Webhook URL not configured");
+      const body = JSON.stringify({
+        alert: {
+          rule: alert.rule,
+          condition: alert.condition,
+          message: alert.message,
+          value: alert.value,
+          threshold: alert.threshold
+        },
+        timestamp: new Date().toISOString()
+      });
+      const resp = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body
+      });
+      if (!resp.ok) throw new Error(`Webhook returned ${resp.status}`);
+      break;
+    }
+
+    case "file": {
+      const filePath = rule.actionConfig?.filePath;
+      if (!filePath) throw new Error("File path not configured");
+      const dir = path.dirname(filePath);
+      await fs.mkdir(dir, { recursive: true });
+      const line = `[${new Date().toISOString()}] ${alert.rule}: ${alert.message}\n`;
+      await fs.appendFile(filePath, line, "utf8");
+      break;
+    }
+  }
+}
+
+/**
+ * Load alert rules from a JSON file.
+ */
+export async function loadAlertRulesFromFile(filePath) {
+  const content = await fs.readFile(filePath, "utf8");
+  const rules = JSON.parse(content);
+  if (!Array.isArray(rules)) {
+    throw new Error("Alert rules file must contain a JSON array");
+  }
+  return rules;
+}
+
+/**
+ * Render alert rules report as markdown.
+ */
+export function renderAlertRulesMarkdown(report) {
+  const lines = [
+    "# GEO Alert Rules Report",
+    "",
+    `**Score:** ${report.score}/100`,
+    `**Rules evaluated:** ${report.rulesEvaluated}`,
+    `**Triggered:** ${report.triggered.length}`,
+    `**Passed:** ${report.passed.length}`,
+    ""
+  ];
+
+  if (report.triggered.length > 0) {
+    lines.push("## Triggered Alerts", "");
+    for (const alert of report.triggered) {
+      lines.push(`- **${alert.rule}** (${alert.condition}): ${alert.message} [action: ${alert.actionExecuted ? "executed" : "failed"}]`);
+    }
+    lines.push("");
+  }
+
+  if (report.passed.length > 0) {
+    lines.push("## Passed Rules", "");
+    for (const p of report.passed) {
+      lines.push(`- ${p.rule}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Summary", "", report.summary, "");
+
+  return lines.join("\n");
+}
+
+/**
+ * Write alert rules output to file.
+ */
+export async function writeAlertRulesOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}