geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/readability.js

@@ -0,0 +1,252 @@
+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-z]+;/gi, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function extractPlainText(content) {
+  if (/<html|<head|<body/i.test(content)) return stripHtml(content);
+  return content.replace(/^---[\s\S]*?---/, "").trim();
+}
+
+function splitSentences(text) {
+  return text
+    .split(/(?<=[.!?。！？])\s+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 5);
+}
+
+function splitWords(text) {
+  return text.split(/\s+/).filter((w) => w.length > 0);
+}
+
+function countSyllables(word) {
+  const cleaned = word.toLowerCase().replace(/[^a-z]/g, "");
+  if (cleaned.length <= 2) return 1;
+
+  let count = 0;
+  const vowels = "aeiouy";
+  let prevVowel = false;
+
+  for (const char of cleaned) {
+    const isVowel = vowels.includes(char);
+    if (isVowel && !prevVowel) count++;
+    prevVowel = isVowel;
+  }
+
+  if (cleaned.endsWith("e") && count > 1) count--;
+  return Math.max(count, 1);
+}
+
+function computeFleschKincaid(words, sentences, syllables) {
+  if (sentences === 0 || words === 0) return 0;
+  return Math.round(
+    (0.39 * (words / sentences) + 11.8 * (syllables / words) - 15.59) * 10
+  ) / 10;
+}
+
+function computeFleschReadingEase(words, sentences, syllables) {
+  if (sentences === 0 || words === 0) return 0;
+  return Math.round(
+    (206.835 - 1.015 * (words / sentences) - 84.6 * (syllables / words)) * 10
+  ) / 10;
+}
+
+function getGradeLabel(grade) {
+  if (grade <= 6) return "Easy (general audience)";
+  if (grade <= 8) return "Standard (most adults)";
+  if (grade <= 12) return "Moderate (educated readers)";
+  if (grade <= 16) return "Difficult (college level)";
+  return "Very difficult (graduate+)";
+}
+
+function getReadingEaseLabel(score) {
+  if (score >= 80) return "Easy";
+  if (score >= 60) return "Standard";
+  if (score >= 40) return "Moderate";
+  if (score >= 20) return "Difficult";
+  return "Very difficult";
+}
+
+function analyzePassiveVoice(sentences) {
+  const passivePattern = /\b(is|are|was|were|been|being|be)\s+([\w]+ed|[\w]+en)\b/gi;
+  let passiveCount = 0;
+
+  for (const sentence of sentences) {
+    if (passivePattern.test(sentence)) {
+      passiveCount++;
+    }
+    passivePattern.lastIndex = 0;
+  }
+
+  return {
+    passiveCount,
+    passiveRatio: sentences.length > 0 ? Math.round((passiveCount / sentences.length) * 100) : 0
+  };
+}
+
+function analyzeSentenceLength(sentences) {
+  if (sentences.length === 0) return { avg: 0, min: 0, max: 0, longCount: 0, shortCount: 0, distribution: {} };
+
+  const lengths = sentences.map((s) => splitWords(s).length);
+  const avg = Math.round(lengths.reduce((a, b) => a + b, 0) / lengths.length);
+  const min = Math.min(...lengths);
+  const max = Math.max(...lengths);
+  const longCount = lengths.filter((l) => l > 30).length;
+  const shortCount = lengths.filter((l) => l < 8).length;
+
+  const distribution = {
+    short: lengths.filter((l) => l < 10).length,
+    medium: lengths.filter((l) => l >= 10 && l <= 20).length,
+    long: lengths.filter((l) => l > 20 && l <= 30).length,
+    veryLong: lengths.filter((l) => l > 30).length
+  };
+
+  return { avg, min, max, longCount, shortCount, distribution };
+}
+
+function estimateReadingTime(wordCount) {
+  const wpm = 238; // Average adult reading speed
+  const minutes = Math.ceil(wordCount / wpm);
+  return minutes;
+}
+
+function buildRecommendations(grade, readingEase, passive, sentenceStats, wordCount) {
+  const recs = [];
+
+  if (grade > 12) {
+    recs.push("Simplify language. Aim for grade level 8-10 for maximum AI citability and reach.");
+  }
+  if (sentenceStats.avg > 25) {
+    recs.push(`Average sentence length is ${sentenceStats.avg} words. Break long sentences (target: 15-20 words).`);
+  }
+  if (sentenceStats.longCount > 3) {
+    recs.push(`${sentenceStats.longCount} sentences exceed 30 words. Split for clarity.`);
+  }
+  if (passive.passiveRatio > 20) {
+    recs.push(`Passive voice used in ${passive.passiveRatio}% of sentences. Prefer active voice for clarity.`);
+  }
+  if (readingEase < 40) {
+    recs.push("Content is hard to read. Use shorter words and simpler sentence structures.");
+  }
+  if (wordCount < 300) {
+    recs.push("Content is thin. AI systems prefer comprehensive content (500+ words).");
+  }
+
+  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 analyzeReadability(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 sentences = splitSentences(plainText);
+  const words = splitWords(plainText);
+  const totalSyllables = words.reduce((sum, w) => sum + countSyllables(w), 0);
+
+  const grade = computeFleschKincaid(words.length, sentences.length, totalSyllables);
+  const readingEase = computeFleschReadingEase(words.length, sentences.length, totalSyllables);
+  const passive = analyzePassiveVoice(sentences);
+  const sentenceStats = analyzeSentenceLength(sentences);
+  const readingTime = estimateReadingTime(words.length);
+  const recommendations = buildRecommendations(grade, readingEase, passive, sentenceStats, words.length);
+
+  const score = Math.round(Math.min(100, Math.max(0,
+    readingEase * 0.4 +
+    (grade <= 10 ? 40 : grade <= 14 ? 20 : 0) +
+    (passive.passiveRatio <= 15 ? 20 : passive.passiveRatio <= 25 ? 10 : 0)
+  )));
+
+  return {
+    kind: "geo-readability",
+    source,
+    wordCount: words.length,
+    sentenceCount: sentences.length,
+    readingTime,
+    fleschKincaidGrade: grade,
+    gradeLabel: getGradeLabel(grade),
+    fleschReadingEase: readingEase,
+    readingEaseLabel: getReadingEaseLabel(readingEase),
+    passiveVoice: passive,
+    sentenceLength: sentenceStats,
+    score,
+    scoreLabel: score >= 70 ? "Good" : score >= 40 ? "Fair" : "Needs improvement",
+    recommendations,
+    summary: `Readability: Grade ${grade} (${getGradeLabel(grade)}). Reading ease: ${readingEase} (${getReadingEaseLabel(readingEase)}). ~${readingTime} min read.`
+  };
+}
+
+export function renderReadabilityMarkdown(report) {
+  const lines = [
+    "# Readability Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Key Metrics",
+    "",
+    `| Metric | Value |`,
+    `|--------|-------|`,
+    `| Word Count | ${report.wordCount} |`,
+    `| Sentence Count | ${report.sentenceCount} |`,
+    `| Reading Time | ~${report.readingTime} min |`,
+    `| Flesch-Kincaid Grade | ${report.fleschKincaidGrade} (${report.gradeLabel}) |`,
+    `| Flesch Reading Ease | ${report.fleschReadingEase} (${report.readingEaseLabel}) |`,
+    `| Passive Voice | ${report.passiveVoice.passiveRatio}% (${report.passiveVoice.passiveCount} sentences) |`,
+    "",
+    "## Sentence Length",
+    "",
+    `- Average: \`${report.sentenceLength.avg}\` words`,
+    `- Range: \`${report.sentenceLength.min}\` - \`${report.sentenceLength.max}\` words`,
+    `- Short (< 10): \`${report.sentenceLength.distribution.short}\``,
+    `- Medium (10-20): \`${report.sentenceLength.distribution.medium}\``,
+    `- Long (20-30): \`${report.sentenceLength.distribution.long}\``,
+    `- Very long (> 30): \`${report.sentenceLength.distribution.veryLong}\``,
+    ""
+  ];
+
+  lines.push("## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Readability is well-optimized for AI and general audiences.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeReadabilityOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}

package/src/security.js

@@ -0,0 +1,249 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+const SECURITY_HEADERS = [
+  { name: "content-security-policy", label: "Content-Security-Policy", weight: 15, critical: true },
+  { name: "x-frame-options", label: "X-Frame-Options", weight: 10, critical: false },
+  { name: "x-content-type-options", label: "X-Content-Type-Options", weight: 10, critical: false },
+  { name: "strict-transport-security", label: "Strict-Transport-Security (HSTS)", weight: 15, critical: true },
+  { name: "referrer-policy", label: "Referrer-Policy", weight: 8, critical: false },
+  { name: "permissions-policy", label: "Permissions-Policy", weight: 8, critical: false },
+  { name: "x-xss-protection", label: "X-XSS-Protection", weight: 5, critical: false }
+];
+
+function analyzeHtmlSecurity(content) {
+  const checks = [];
+
+  // Viewport
+  const hasViewport = /<meta[^>]+name=["']viewport["']/i.test(content);
+  checks.push({ key: "viewport", label: "Viewport meta tag", passed: hasViewport, severity: hasViewport ? "pass" : "warning" });
+
+  // HTTPS references
+  const httpLinks = (content.match(/(?:src|href|action)=["']http:\/\//gi) || []).length;
+  const hasMixedContent = httpLinks > 0;
+  checks.push({
+    key: "mixedContent",
+    label: "No mixed content (HTTP resources on HTTPS page)",
+    passed: !hasMixedContent,
+    severity: hasMixedContent ? "error" : "pass",
+    detail: hasMixedContent ? `${httpLinks} HTTP resource reference(s) found` : null
+  });
+
+  // Robots meta
+  const robotsMeta = content.match(/<meta[^>]+name=["']robots["'][^>]+content=["']([^"']+)["']/i);
+  const robotsDirectives = robotsMeta ? robotsMeta[1].toLowerCase().split(",").map((d) => d.trim()) : [];
+  const hasNoindex = robotsDirectives.includes("noindex");
+  const hasNofollow = robotsDirectives.includes("nofollow");
+
+  checks.push({
+    key: "robotsMeta",
+    label: "Robots meta tag (indexing allowed)",
+    passed: !hasNoindex,
+    severity: hasNoindex ? "warning" : "pass",
+    detail: robotsMeta ? `Directives: ${robotsDirectives.join(", ")}` : "No robots meta tag (defaults: index, follow)"
+  });
+
+  if (hasNofollow) {
+    checks.push({
+      key: "nofollow",
+      label: "Nofollow directive",
+      passed: false,
+      severity: "info",
+      detail: "Page has nofollow — link equity won't flow to linked pages"
+    });
+  }
+
+  // X-UA-Compatible (legacy, informational only)
+
+  // Charset
+  const hasCharset = /<meta[^>]+charset/i.test(content) || /charset=/i.test(content);
+  checks.push({ key: "charset", label: "Character encoding declared", passed: hasCharset, severity: hasCharset ? "pass" : "warning" });
+
+  // Language
+  const hasLang = /<html[^>]+lang=/i.test(content);
+  checks.push({ key: "lang", label: "HTML lang attribute", passed: hasLang, severity: hasLang ? "pass" : "warning" });
+
+  // HTTPS canonical
+  const canonical = content.match(/<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i);
+  const canonicalIsHttps = canonical ? canonical[1].startsWith("https://") : false;
+  if (canonical) {
+    checks.push({
+      key: "httpsCanonical",
+      label: "Canonical URL uses HTTPS",
+      passed: canonicalIsHttps,
+      severity: canonicalIsHttps ? "pass" : "error"
+    });
+  }
+
+  return checks;
+}
+
+function analyzeHeaders(headers) {
+  const results = [];
+
+  for (const spec of SECURITY_HEADERS) {
+    const value = headers[spec.name] || null;
+    results.push({
+      header: spec.label,
+      key: spec.name,
+      present: Boolean(value),
+      value: value ? value.slice(0, 100) : null,
+      weight: spec.weight,
+      critical: spec.critical
+    });
+  }
+
+  return results;
+}
+
+function computeScore(htmlChecks, headerResults, isHttps) {
+  let score = 0;
+
+  // HTTPS base
+  score += isHttps ? 20 : 0;
+
+  // HTML checks
+  const htmlPassed = htmlChecks.filter((c) => c.passed).length;
+  score += Math.round((htmlPassed / Math.max(htmlChecks.length, 1)) * 30);
+
+  // Security headers
+  if (headerResults) {
+    const totalWeight = headerResults.reduce((sum, h) => sum + h.weight, 0);
+    const earnedWeight = headerResults.filter((h) => h.present).reduce((sum, h) => sum + h.weight, 0);
+    score += Math.round((earnedWeight / totalWeight) * 50);
+  } else {
+    score += 25; // Can't check headers for local files, give partial credit
+  }
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function buildRecommendations(htmlChecks, headerResults, isHttps) {
+  const recs = [];
+
+  if (!isHttps) {
+    recs.push("Migrate to HTTPS. It's a ranking signal and required for security.");
+  }
+
+  for (const check of htmlChecks) {
+    if (!check.passed && check.severity !== "info") {
+      recs.push(`Fix: ${check.label}${check.detail ? ` — ${check.detail}` : ""}`);
+    }
+  }
+
+  if (headerResults) {
+    const missing = headerResults.filter((h) => !h.present);
+    const critical = missing.filter((h) => h.critical);
+    const optional = missing.filter((h) => !h.critical);
+
+    if (critical.length > 0) {
+      recs.push(`Add critical security headers: ${critical.map((h) => h.header).join(", ")}`);
+    }
+    if (optional.length > 0) {
+      recs.push(`Add recommended security headers: ${optional.map((h) => h.header).join(", ")}`);
+    }
+  }
+
+  return recs;
+}
+
+async function fetchWithHeaders(url) {
+  const response = await fetch(url, {
+    redirect: "follow",
+    headers: { "user-agent": "geo-ai-search-optimization/2.2.0" },
+    signal: AbortSignal.timeout(10_000)
+  });
+  const text = await response.text();
+  const headers = {};
+  for (const [key, value] of response.headers.entries()) {
+    headers[key.toLowerCase()] = value;
+  }
+  return {
+    ok: response.ok,
+    status: response.status,
+    url: response.url,
+    isHttps: response.url.startsWith("https://"),
+    headers,
+    text
+  };
+}
+
+export async function analyzeSecurity(input, options = {}) {
+  let content;
+  let source;
+  let headers = null;
+  let isHttps = true; // Assume true for local files
+
+  if (/^https?:\/\//i.test(input)) {
+    const result = await fetchWithHeaders(input);
+    content = result.text;
+    source = result.url;
+    headers = result.headers;
+    isHttps = result.isHttps;
+  } else {
+    const filePath = path.resolve(input);
+    content = await fs.readFile(filePath, "utf8");
+    source = filePath;
+  }
+
+  const htmlChecks = analyzeHtmlSecurity(content);
+  const headerResults = headers ? analyzeHeaders(headers) : null;
+  const score = computeScore(htmlChecks, headerResults, isHttps);
+  const recommendations = buildRecommendations(htmlChecks, headerResults, isHttps);
+
+  return {
+    kind: "geo-security",
+    source,
+    isHttps,
+    score,
+    scoreLabel: score >= 80 ? "Good" : score >= 50 ? "Fair" : "Needs work",
+    htmlChecks,
+    securityHeaders: headerResults,
+    recommendations,
+    summary: `Security score: ${score}/100. HTTPS: ${isHttps ? "yes" : "no"}. ${recommendations.length} issue(s) found.`
+  };
+}
+
+export function renderSecurityMarkdown(report) {
+  const lines = [
+    "# Security Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- HTTPS: \`${report.isHttps}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## HTML Security Checks",
+    ""
+  ];
+
+  for (const check of report.htmlChecks) {
+    const icon = check.passed ? "✅" : (check.severity === "error" ? "❌" : "⚠️");
+    lines.push(`- ${icon} ${check.label}${check.detail ? ` — ${check.detail}` : ""}`);
+  }
+
+  if (report.securityHeaders) {
+    lines.push("", "## Security Headers", "", "| Header | Present | Value |", "|--------|---------|-------|");
+    for (const h of report.securityHeaders) {
+      const icon = h.present ? "✅" : (h.critical ? "❌" : "—");
+      lines.push(`| ${h.header} | ${icon} | ${h.value || "—"} |`);
+    }
+  }
+
+  lines.push("", "## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Security configuration looks good.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeSecurityOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}