geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/eeat.js

@@ -0,0 +1,251 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+function stripHtml(text) {
+  return text
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/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();
+}
+
+// Experience signals: first-hand, personal, case study, hands-on
+const EXPERIENCE_PATTERNS = [
+  { pattern: /\b(I|we)\s+(tested|tried|used|built|implemented|deployed|ran|conducted|measured|observed)\b/gi, label: "First-person experience" },
+  { pattern: /\b(case study|real[- ]world|hands[- ]on|in practice|from experience|in my experience|our experience)\b/gi, label: "Experience claim" },
+  { pattern: /\b(screenshot|demo|walkthrough|step[- ]by[- ]step|tutorial|how I|how we)\b/gi, label: "Practical demonstration" },
+  { pattern: /\b(lesson learned|mistake|challenge|obstacle|solution we found)\b/gi, label: "Experience narrative" },
+  { pattern: /\b(client|customer|user)\s+(feedback|review|testimonial|said|reported)\b/gi, label: "User experience" }
+];
+
+// Expertise signals: technical depth, methodology, credentials
+const EXPERTISE_PATTERNS = [
+  { pattern: /\b(methodology|framework|algorithm|architecture|protocol|specification)\b/gi, label: "Technical methodology" },
+  { pattern: /\b(PhD|professor|researcher|engineer|scientist|expert|specialist|certified|credential)\b/gi, label: "Credential mention" },
+  { pattern: /\b(analysis|benchmark|experiment|hypothesis|correlation|regression|statistical)\b/gi, label: "Analytical depth" },
+  { pattern: /\b(best practice|anti[- ]pattern|trade[- ]off|caveat|limitation|edge case)\b/gi, label: "Expert nuance" },
+  { pattern: /\b(according to|based on|as described in|per the|RFC|ISO|IEEE|W3C)\b/gi, label: "Standards reference" }
+];
+
+// Authoritativeness signals: citations, institutional backing, recognition
+const AUTHORITY_PATTERNS = [
+  { pattern: /\b(cited by|referenced by|published in|featured in|recognized by|awarded)\b/gi, label: "External recognition" },
+  { pattern: /\b(university|institute|laboratory|foundation|consortium|association)\b/gi, label: "Institutional backing" },
+  { pattern: /\b(peer[- ]reviewed|journal|conference|proceedings|publication)\b/gi, label: "Academic publication" },
+  { pattern: /https?:\/\/[^\s)>]+/gi, label: "Source link" },
+  { pattern: /\b(source|reference|citation|bibliography|works cited)\b/gi, label: "Citation markers" }
+];
+
+// Trustworthiness signals: transparency, disclosure, accuracy
+const TRUST_PATTERNS = [
+  { pattern: /\b(disclosure|disclaimer|conflict of interest|affiliate|sponsored|paid)\b/gi, label: "Disclosure" },
+  { pattern: /\b(updated|last reviewed|reviewed by|fact[- ]checked|verified)\b/gi, label: "Content freshness" },
+  { pattern: /\b(privacy policy|terms of service|cookie policy|GDPR|CCPA)\b/gi, label: "Policy transparency" },
+  { pattern: /\b(correction|erratum|update note|editor'?s note)\b/gi, label: "Correction transparency" },
+  { pattern: /\b(contact|email|phone|address|about us|our team)\b/gi, label: "Contact information" }
+];
+
+function countSignals(text, patterns) {
+  const matches = [];
+  for (const { pattern, label } of patterns) {
+    const found = text.match(pattern) || [];
+    if (found.length > 0) {
+      matches.push({ label, count: found.length, examples: found.slice(0, 3).map((m) => m.trim()) });
+    }
+  }
+  return matches;
+}
+
+function computeDimensionScore(matches, maxScore) {
+  const totalMatches = matches.reduce((sum, m) => sum + m.count, 0);
+  const uniquePatterns = matches.length;
+
+  let score = 0;
+  score += Math.min(uniquePatterns * 15, 60);
+  score += Math.min(totalMatches * 3, 40);
+
+  return Math.min(score, maxScore);
+}
+
+function analyzeAuthorPresence(content) {
+  const signals = [];
+
+  if (/<meta[^>]+name=["']author["'][^>]+content=["']([^"']+)["']/i.test(content)) {
+    signals.push("meta author tag");
+  }
+  if (/"author"\s*:\s*\{/i.test(content) || /"author"\s*:\s*"/i.test(content)) {
+    signals.push("JSON-LD author");
+  }
+  if (/\bby\s+[A-Z][a-z]+\s+[A-Z][a-z]+/m.test(content)) {
+    signals.push("byline pattern");
+  }
+  if (/\bdatePublished\b|\bdateModified\b/i.test(content)) {
+    signals.push("date signals in structured data");
+  }
+  if (/<time\b[^>]*datetime/i.test(content)) {
+    signals.push("HTML time element");
+  }
+  if (/\b(reviewed by|edited by|fact[- ]checked by)\b/i.test(content)) {
+    signals.push("editorial review signal");
+  }
+
+  return signals;
+}
+
+function buildRecommendations(experience, expertise, authority, trust, authorSignals) {
+  const recs = [];
+
+  if (experience.length === 0) {
+    recs.push("Add first-person experience narratives, case studies, or hands-on demonstrations to show real-world experience.");
+  }
+  if (expertise.length < 2) {
+    recs.push("Increase technical depth with methodology descriptions, expert nuance (caveats, trade-offs), or standards references.");
+  }
+  if (authority.length < 2) {
+    recs.push("Add more source links, cite external research, or reference institutional backing to strengthen authoritativeness.");
+  }
+  if (trust.length < 2) {
+    recs.push("Improve transparency with disclosure statements, content freshness indicators (last reviewed date), and contact information.");
+  }
+  if (authorSignals.length === 0) {
+    recs.push("Add author attribution: byline, author meta tag, JSON-LD author field, and reviewer credit.");
+  }
+  if (!authorSignals.includes("date signals in structured data") && !authorSignals.includes("HTML time element")) {
+    recs.push("Add datePublished and dateModified to structured data and visible content.");
+  }
+
+  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 analyzeEeat(input, options = {}) {
+  let rawContent;
+  let source;
+
+  if (/^https?:\/\//i.test(input)) {
+    rawContent = await fetchContent(input);
+    source = input;
+  } else {
+    const filePath = path.resolve(input);
+    rawContent = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  const plainText = extractPlainText(rawContent);
+  const wordCount = plainText.split(/\s+/).length;
+
+  const experience = countSignals(plainText, EXPERIENCE_PATTERNS);
+  const expertise = countSignals(plainText, EXPERTISE_PATTERNS);
+  const authority = countSignals(plainText, AUTHORITY_PATTERNS);
+  const trust = countSignals(plainText, TRUST_PATTERNS);
+  const authorSignals = analyzeAuthorPresence(rawContent);
+
+  const experienceScore = computeDimensionScore(experience, 100);
+  const expertiseScore = computeDimensionScore(expertise, 100);
+  const authorityScore = computeDimensionScore(authority, 100);
+  const trustScore = computeDimensionScore(trust, 100);
+
+  const overallScore = Math.round(
+    experienceScore * 0.2 + expertiseScore * 0.3 + authorityScore * 0.25 + trustScore * 0.25
+  );
+
+  const recommendations = buildRecommendations(experience, expertise, authority, trust, authorSignals);
+
+  return {
+    kind: "geo-eeat",
+    source,
+    wordCount,
+    score: overallScore,
+    scoreLabel: getScoreLabel(overallScore),
+    dimensions: {
+      experience: { score: experienceScore, signals: experience },
+      expertise: { score: expertiseScore, signals: expertise },
+      authoritativeness: { score: authorityScore, signals: authority },
+      trustworthiness: { score: trustScore, signals: trust }
+    },
+    authorPresence: authorSignals,
+    recommendations,
+    summary: `E-E-A-T score: ${overallScore}/100 (${getScoreLabel(overallScore)}). Experience: ${experienceScore}, Expertise: ${expertiseScore}, Authority: ${authorityScore}, Trust: ${trustScore}.`
+  };
+}
+
+function getScoreLabel(score) {
+  if (score >= 80) return "Strong";
+  if (score >= 60) return "Moderate";
+  if (score >= 40) return "Weak";
+  return "Very weak";
+}
+
+export function renderEeatMarkdown(report) {
+  const lines = [
+    "# E-E-A-T Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Overall Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Word Count: \`${report.wordCount}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Dimension Scores",
+    "",
+    `| Dimension | Score | Rating |`,
+    `|-----------|-------|--------|`,
+    `| Experience | ${report.dimensions.experience.score}/100 | ${getScoreLabel(report.dimensions.experience.score)} |`,
+    `| Expertise | ${report.dimensions.expertise.score}/100 | ${getScoreLabel(report.dimensions.expertise.score)} |`,
+    `| Authoritativeness | ${report.dimensions.authoritativeness.score}/100 | ${getScoreLabel(report.dimensions.authoritativeness.score)} |`,
+    `| Trustworthiness | ${report.dimensions.trustworthiness.score}/100 | ${getScoreLabel(report.dimensions.trustworthiness.score)} |`,
+    ""
+  ];
+
+  for (const [dim, data] of Object.entries(report.dimensions)) {
+    if (data.signals.length > 0) {
+      lines.push(`## ${dim.charAt(0).toUpperCase() + dim.slice(1)} Signals`, "");
+      for (const signal of data.signals) {
+        lines.push(`- ${signal.label}: \`${signal.count}\` match(es) — e.g. ${signal.examples.map((e) => `"${e}"`).join(", ")}`);
+      }
+      lines.push("");
+    }
+  }
+
+  if (report.authorPresence.length > 0) {
+    lines.push("## Author Presence", "");
+    for (const signal of report.authorPresence) {
+      lines.push(`- ✅ ${signal}`);
+    }
+    lines.push("");
+  } else {
+    lines.push("## Author Presence", "", "- ❌ No author attribution detected.", "");
+  }
+
+  lines.push("## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- E-E-A-T signals are well-represented.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeEeatOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/freshness.js

@@ -0,0 +1,281 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+const DATE_PATTERNS = [
+  // ISO dates
+  { pattern: /\b(20[12]\d-[01]\d-[0-3]\d)/g, format: "ISO" },
+  // US format: Month DD, YYYY
+  { pattern: /\b(January|February|March|April|May|June|July|August|September|October|November|December)\s+(\d{1,2}),?\s+(20[12]\d)/gi, format: "US" },
+  // Structured data dates
+  { pattern: /"datePublished"\s*:\s*"([^"]+)"/g, format: "schema-published" },
+  { pattern: /"dateModified"\s*:\s*"([^"]+)"/g, format: "schema-modified" },
+  { pattern: /"dateCreated"\s*:\s*"([^"]+)"/g, format: "schema-created" },
+  // HTML time element
+  { pattern: /<time[^>]+datetime=["']([^"']+)["']/gi, format: "html-time" },
+  // Meta tags
+  { pattern: /name=["'](?:date|article:published_time|article:modified_time)["'][^>]+content=["']([^"']+)["']/gi, format: "meta" },
+  { pattern: /content=["']([^"']+)["'][^>]+name=["'](?:date|article:published_time|article:modified_time)["']/gi, format: "meta-reverse" },
+  // Common patterns
+  { pattern: /\b(?:Published|Updated|Posted|Modified|Created|Reviewed|Last updated)[:\s]+(\d{4}-\d{2}-\d{2}|\w+\s+\d{1,2},?\s+\d{4})/gi, format: "visible-label" }
+];
+
+const MONTH_MAP = {
+  january: 0, february: 1, march: 2, april: 3, may: 4, june: 5,
+  july: 6, august: 7, september: 8, october: 9, november: 10, december: 11
+};
+
+function parseDate(dateStr) {
+  // Try ISO first
+  const isoMatch = dateStr.match(/(\d{4})-(\d{2})-(\d{2})/);
+  if (isoMatch) {
+    const d = new Date(isoMatch[0]);
+    if (!Number.isNaN(d.getTime())) return d;
+  }
+
+  // Try US format
+  const usMatch = dateStr.match(/(January|February|March|April|May|June|July|August|September|October|November|December)\s+(\d{1,2}),?\s+(\d{4})/i);
+  if (usMatch) {
+    const month = MONTH_MAP[usMatch[1].toLowerCase()];
+    if (month !== undefined) {
+      return new Date(Number.parseInt(usMatch[3]), month, Number.parseInt(usMatch[2]));
+    }
+  }
+
+  // Generic attempt
+  const d = new Date(dateStr);
+  if (!Number.isNaN(d.getTime()) && d.getFullYear() >= 2000) return d;
+  return null;
+}
+
+function extractDates(content) {
+  const found = [];
+  const seen = new Set();
+
+  for (const { pattern, format } of DATE_PATTERNS) {
+    let match;
+    const regex = new RegExp(pattern.source, pattern.flags);
+    while ((match = regex.exec(content)) !== null) {
+      const raw = match[1] || match[0];
+      const parsed = parseDate(raw);
+      if (parsed && !seen.has(parsed.toISOString().slice(0, 10))) {
+        seen.add(parsed.toISOString().slice(0, 10));
+        found.push({
+          raw: raw.trim().slice(0, 60),
+          date: parsed.toISOString().slice(0, 10),
+          source: format,
+          timestamp: parsed.getTime()
+        });
+      }
+    }
+  }
+
+  return found.sort((a, b) => b.timestamp - a.timestamp);
+}
+
+function computeAge(dates) {
+  if (dates.length === 0) return null;
+
+  const now = new Date();
+  const published = dates.find((d) => d.source.includes("published") || d.source === "visible-label") || dates[dates.length - 1];
+  const modified = dates.find((d) => d.source.includes("modified")) || dates[0];
+
+  const publishedDate = new Date(published.date);
+  const modifiedDate = new Date(modified.date);
+
+  const publishedAgeDays = Math.floor((now - publishedDate) / (1000 * 60 * 60 * 24));
+  const modifiedAgeDays = Math.floor((now - modifiedDate) / (1000 * 60 * 60 * 24));
+
+  return {
+    publishedDate: published.date,
+    modifiedDate: modified.date,
+    publishedAgeDays,
+    modifiedAgeDays,
+    publishedAgeLabel: formatAge(publishedAgeDays),
+    modifiedAgeLabel: formatAge(modifiedAgeDays),
+    isStale: modifiedAgeDays > 180,
+    isOld: modifiedAgeDays > 365
+  };
+}
+
+function formatAge(days) {
+  if (days < 7) return `${days} day(s)`;
+  if (days < 30) return `${Math.floor(days / 7)} week(s)`;
+  if (days < 365) return `${Math.floor(days / 30)} month(s)`;
+  return `${Math.round((days / 365) * 10) / 10} year(s)`;
+}
+
+function analyzeFreshnessSignals(content) {
+  const signals = [];
+
+  if (/"datePublished"/i.test(content)) signals.push("datePublished in structured data");
+  if (/"dateModified"/i.test(content)) signals.push("dateModified in structured data");
+  if (/<time\b/i.test(content)) signals.push("HTML <time> element");
+  if (/article:published_time/i.test(content)) signals.push("article:published_time meta");
+  if (/article:modified_time/i.test(content)) signals.push("article:modified_time meta");
+  if (/\b(updated|last reviewed|last modified|revised)\b/i.test(content)) signals.push("Visible freshness label");
+  if (/"dateCreated"/i.test(content)) signals.push("dateCreated in structured data");
+
+  return signals;
+}
+
+function computeScore(dates, age, signals) {
+  if (dates.length === 0) return 10; // No dates at all
+
+  let score = 30; // Has at least one date
+
+  // Signal variety
+  score += Math.min(signals.length * 8, 24);
+
+  // Age-based scoring
+  if (age) {
+    if (age.modifiedAgeDays <= 30) score += 25;
+    else if (age.modifiedAgeDays <= 90) score += 20;
+    else if (age.modifiedAgeDays <= 180) score += 12;
+    else if (age.modifiedAgeDays <= 365) score += 5;
+
+    // Has both published and modified
+    if (age.publishedDate !== age.modifiedDate) score += 10;
+  }
+
+  // Structured data dates (highest value)
+  const hasSchemaDate = dates.some((d) => d.source.startsWith("schema-"));
+  if (hasSchemaDate) score += 11;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function buildRecommendations(dates, age, signals) {
+  const recs = [];
+
+  if (dates.length === 0) {
+    recs.push("Add datePublished and dateModified to your structured data (JSON-LD).");
+    recs.push("Add visible publication and update dates to your content.");
+    return recs;
+  }
+
+  if (!signals.includes("datePublished in structured data")) {
+    recs.push("Add datePublished to your JSON-LD structured data.");
+  }
+  if (!signals.includes("dateModified in structured data")) {
+    recs.push("Add dateModified to your JSON-LD structured data.");
+  }
+  if (!signals.includes("Visible freshness label")) {
+    recs.push("Add a visible 'Last updated' or 'Reviewed on' date to your page.");
+  }
+
+  if (age) {
+    if (age.isStale) {
+      recs.push(`Content was last modified ${age.modifiedAgeLabel} ago. Review and update to maintain freshness.`);
+    }
+    if (age.isOld) {
+      recs.push("Content is over 1 year old. AI systems may deprioritize stale content.");
+    }
+    if (age.publishedDate === age.modifiedDate) {
+      recs.push("datePublished and dateModified are the same. Update dateModified when content changes.");
+    }
+  }
+
+  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 analyzeFreshness(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 dates = extractDates(content);
+  const age = computeAge(dates);
+  const signals = analyzeFreshnessSignals(content);
+  const score = computeScore(dates, age, signals);
+  const recommendations = buildRecommendations(dates, age, signals);
+
+  return {
+    kind: "geo-freshness",
+    source,
+    datesFound: dates.length,
+    dates: dates.slice(0, 20),
+    age,
+    freshnessSignals: signals,
+    score,
+    scoreLabel: score >= 80 ? "Fresh" : score >= 50 ? "Aging" : score >= 30 ? "Stale" : "No dates",
+    recommendations,
+    summary: age
+      ? `Content freshness: ${score}/100. Published: ${age.publishedDate}. Last modified: ${age.modifiedDate} (${age.modifiedAgeLabel} ago).`
+      : `Content freshness: ${score}/100. No publication dates detected.`
+  };
+}
+
+export function renderFreshnessMarkdown(report) {
+  const lines = [
+    "# Content Freshness Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Dates found: \`${report.datesFound}\``,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  if (report.age) {
+    lines.push(
+      "## Content Age",
+      "",
+      `- Published: \`${report.age.publishedDate}\` (${report.age.publishedAgeLabel} ago)`,
+      `- Last modified: \`${report.age.modifiedDate}\` (${report.age.modifiedAgeLabel} ago)`,
+      `- Stale: \`${report.age.isStale}\``,
+      `- Old (> 1 year): \`${report.age.isOld}\``,
+      ""
+    );
+  }
+
+  if (report.freshnessSignals.length > 0) {
+    lines.push("## Freshness Signals", "");
+    for (const signal of report.freshnessSignals) {
+      lines.push(`- ✅ ${signal}`);
+    }
+    lines.push("");
+  }
+
+  if (report.dates.length > 0) {
+    lines.push("## Detected Dates", "");
+    for (const date of report.dates.slice(0, 10)) {
+      lines.push(`- \`${date.date}\` (${date.source}) — "${date.raw}"`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Content freshness signals are well-configured.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeFreshnessOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}