geo-ai-search-optimization 2.6.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.6.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.6.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.6.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/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);
+}

package/src/canonical-resolver.js

@@ -0,0 +1,328 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fetchText, fetchResponse } from "./fetch-utils.js";
+import { writeScanOutput } from "./scan.js";
+
+/**
+ * Extract <link rel="canonical" href="..."> from HTML.
+ */
+function extractLinkCanonical(html) {
+  // Match both attribute orders: rel before href, and href before rel
+  const pattern1 = /<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)["'][^>]*>/i;
+  const pattern2 = /<link[^>]+href=["']([^"']+)["'][^>]+rel=["']canonical["'][^>]*>/i;
+  const match = html.match(pattern1) || html.match(pattern2);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Extract <meta property="og:url" content="..."> from HTML.
+ */
+function extractOgUrl(html) {
+  const pattern1 = /<meta[^>]+property=["']og:url["'][^>]+content=["']([^"']*)["'][^>]*>/i;
+  const pattern2 = /<meta[^>]+content=["']([^"']*)["'][^>]+property=["']og:url["'][^>]*>/i;
+  const match = html.match(pattern1) || html.match(pattern2);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Extract canonical from HTTP Link header.
+ * Format: <https://example.com/page>; rel="canonical"
+ */
+function extractHttpHeaderCanonical(headers) {
+  const linkHeader = headers?.link || headers?.Link;
+  if (!linkHeader) return null;
+  const match = linkHeader.match(/<([^>]+)>\s*;\s*rel=["']canonical["']/i);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Normalize URL for comparison (lowercase host, remove trailing slash on path, etc.)
+ */
+function normalizeForComparison(url) {
+  try {
+    const parsed = new URL(url);
+    return {
+      protocol: parsed.protocol,
+      hostname: parsed.hostname.toLowerCase(),
+      pathname: parsed.pathname,
+      full: parsed.href
+    };
+  } catch {
+    return null;
+  }
+}
+
+function checkTrailingSlashConsistency(url1, url2) {
+  if (!url1 || !url2) return true;
+  try {
+    const p1 = new URL(url1).pathname;
+    const p2 = new URL(url2).pathname;
+    // Both root "/" are fine
+    if (p1 === "/" && p2 === "/") return true;
+    // Check if one has trailing slash and the other doesn't (ignoring root)
+    const stripped1 = p1.replace(/\/$/, "") || "/";
+    const stripped2 = p2.replace(/\/$/, "") || "/";
+    if (stripped1 === stripped2 && p1 !== p2) return false;
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+function checkWwwConsistency(url1, url2) {
+  if (!url1 || !url2) return true;
+  try {
+    const h1 = new URL(url1).hostname.toLowerCase();
+    const h2 = new URL(url2).hostname.toLowerCase();
+    const hasWww1 = h1.startsWith("www.");
+    const hasWww2 = h2.startsWith("www.");
+    if (hasWww1 !== hasWww2) {
+      // Check they refer to the same base domain
+      const base1 = h1.replace(/^www\./, "");
+      const base2 = h2.replace(/^www\./, "");
+      if (base1 === base2) return false;
+    }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+function computeScore(issues) {
+  let score = 100;
+  for (const issue of issues) {
+    if (issue.type === "no-canonical") score -= 30;
+    else if (issue.type === "signals-conflict") score -= 20;
+    else if (issue.type === "not-https") score -= 15;
+    else if (issue.type === "trailing-slash-inconsistency") score -= 10;
+    else if (issue.type === "www-inconsistency") score -= 10;
+    else if (issue.type === "not-self-referencing") score -= 5;
+  }
+  return Math.max(0, Math.min(100, score));
+}
+
+function getScoreLabel(score) {
+  if (score >= 80) return "Good";
+  if (score >= 60) return "Fair";
+  if (score >= 40) return "Issues Found";
+  return "Critical Issues";
+}
+
+export async function resolveCanonical(input, options = {}) {
+  let html;
+  let source;
+  let pageUrl = null;
+  let responseHeaders = {};
+
+  const isUrl = /^https?:\/\//i.test(input);
+
+  if (isUrl) {
+    const resp = await fetchResponse(input);
+    html = resp.text;
+    source = input;
+    pageUrl = resp.url || input;
+    responseHeaders = resp.headers || {};
+  } else {
+    const filePath = path.resolve(input);
+    html = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  // Extract canonical signals
+  const linkTag = extractLinkCanonical(html);
+  const ogUrl = extractOgUrl(html);
+  const httpHeader = extractHttpHeaderCanonical(responseHeaders);
+
+  // Determine resolved canonical (priority: link tag > http header > og:url)
+  const resolvedCanonical = linkTag || httpHeader || ogUrl || null;
+
+  const issues = [];
+  const recommendations = [];
+
+  // Check: no canonical at all
+  const hasCanonical = Boolean(linkTag || httpHeader);
+  if (!hasCanonical) {
+    issues.push({
+      type: "no-canonical",
+      severity: "error",
+      message: "No canonical URL found (neither <link rel=\"canonical\"> nor HTTP Link header)."
+    });
+    recommendations.push("Add a <link rel=\"canonical\"> tag to the <head> of the page.");
+  }
+
+  // Check: signals consistency
+  const signals = [linkTag, ogUrl, httpHeader].filter(Boolean);
+  let signalsConsistent = true;
+  if (signals.length > 1) {
+    const normalized = signals.map((s) => {
+      try { return new URL(s).href; } catch { return s; }
+    });
+    const unique = new Set(normalized);
+    if (unique.size > 1) {
+      signalsConsistent = false;
+      issues.push({
+        type: "signals-conflict",
+        severity: "error",
+        message: `Canonical signals conflict: link tag="${linkTag || "none"}", og:url="${ogUrl || "none"}", HTTP header="${httpHeader || "none"}".`
+      });
+      recommendations.push("Ensure <link rel=\"canonical\">, og:url, and HTTP Link header all point to the same URL.");
+    }
+  }
+
+  // Check: HTTPS
+  let isHttps = true;
+  if (resolvedCanonical) {
+    isHttps = /^https:\/\//i.test(resolvedCanonical);
+    if (!isHttps) {
+      issues.push({
+        type: "not-https",
+        severity: "warning",
+        message: `Canonical URL uses HTTP instead of HTTPS: ${resolvedCanonical}`
+      });
+      recommendations.push("Use HTTPS for the canonical URL.");
+    }
+  }
+
+  // Check: self-referencing
+  let isSelfReferencing = false;
+  if (pageUrl && resolvedCanonical) {
+    try {
+      const pageNorm = new URL(pageUrl).href;
+      const canonNorm = new URL(resolvedCanonical).href;
+      isSelfReferencing = pageNorm === canonNorm;
+    } catch {
+      isSelfReferencing = false;
+    }
+    if (!isSelfReferencing) {
+      issues.push({
+        type: "not-self-referencing",
+        severity: "warning",
+        message: `Canonical points to a different URL than the page. Page: "${pageUrl}", Canonical: "${resolvedCanonical}". This may be intentional.`
+      });
+      recommendations.push("Verify the canonical URL is intentionally different from the page URL.");
+    }
+  } else if (!isUrl && resolvedCanonical) {
+    // For file inputs, we can't determine self-referencing
+    isSelfReferencing = false;
+  }
+
+  // Check: trailing slash consistency
+  let trailingSlashConsistent = true;
+  if (pageUrl && resolvedCanonical) {
+    trailingSlashConsistent = checkTrailingSlashConsistency(pageUrl, resolvedCanonical);
+    if (!trailingSlashConsistent) {
+      issues.push({
+        type: "trailing-slash-inconsistency",
+        severity: "warning",
+        message: `Trailing slash inconsistency between page URL and canonical: "${pageUrl}" vs "${resolvedCanonical}".`
+      });
+      recommendations.push("Ensure consistent trailing slash usage between page URL and canonical URL.");
+    }
+  }
+
+  // Check: www consistency
+  let wwwConsistent = true;
+  if (pageUrl && resolvedCanonical) {
+    wwwConsistent = checkWwwConsistency(pageUrl, resolvedCanonical);
+    if (!wwwConsistent) {
+      issues.push({
+        type: "www-inconsistency",
+        severity: "warning",
+        message: `www inconsistency between page URL and canonical: "${pageUrl}" vs "${resolvedCanonical}".`
+      });
+      recommendations.push("Use consistent www/non-www across page URL and canonical URL.");
+    }
+  }
+
+  const score = computeScore(issues);
+  const scoreLabel = getScoreLabel(score);
+
+  const checks = {
+    hasCanonical,
+    isSelfReferencing,
+    isHttps,
+    signalsConsistent,
+    trailingSlashConsistent,
+    wwwConsistent
+  };
+
+  const summaryParts = [`Canonical: ${score}/100 (${scoreLabel}).`];
+  if (resolvedCanonical) {
+    summaryParts.push(`Resolved: ${resolvedCanonical}`);
+  } else {
+    summaryParts.push("No canonical found.");
+  }
+  if (issues.length > 0) {
+    summaryParts.push(`${issues.length} issue(s) detected.`);
+  }
+
+  return {
+    kind: "geo-canonical-resolver",
+    source,
+    pageUrl,
+    canonical: { linkTag, ogUrl, httpHeader },
+    resolvedCanonical,
+    issues,
+    checks,
+    score,
+    scoreLabel,
+    recommendations,
+    summary: summaryParts.join(" ")
+  };
+}
+
+export function renderCanonicalResolverMarkdown(report) {
+  const lines = [
+    "# Canonical URL Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Canonical Signals",
+    "",
+    `| Signal | Value |`,
+    `|--------|-------|`,
+    `| \`<link rel="canonical">\` | ${report.canonical.linkTag || "Not found"} |`,
+    `| \`og:url\` | ${report.canonical.ogUrl || "Not found"} |`,
+    `| HTTP Link header | ${report.canonical.httpHeader || "Not found"} |`,
+    `| Resolved canonical | ${report.resolvedCanonical || "None"} |`,
+    ""
+  ];
+
+  if (report.pageUrl) {
+    lines.push(`- Page URL: \`${report.pageUrl}\``);
+  }
+
+  lines.push("", "## Checks", "", "| Check | Status |", "|-------|--------|");
+  lines.push(`| Has canonical | ${report.checks.hasCanonical ? "Pass" : "Fail"} |`);
+  lines.push(`| Self-referencing | ${report.checks.isSelfReferencing ? "Yes" : "No"} |`);
+  lines.push(`| HTTPS | ${report.checks.isHttps ? "Pass" : "Fail"} |`);
+  lines.push(`| Signals consistent | ${report.checks.signalsConsistent ? "Pass" : "Fail"} |`);
+  lines.push(`| Trailing slash consistent | ${report.checks.trailingSlashConsistent ? "Pass" : "Fail"} |`);
+  lines.push(`| www consistent | ${report.checks.wwwConsistent ? "Pass" : "Fail"} |`);
+
+  if (report.issues.length > 0) {
+    lines.push("", "## Issues", "");
+    for (const issue of report.issues) {
+      const icon = issue.severity === "error" ? "ERROR" : "WARNING";
+      lines.push(`- [${icon}] ${issue.message}`);
+    }
+  }
+
+  lines.push("", "## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Canonical URL configuration looks good.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeCanonicalResolverOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}