geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/heading-structure.js

@@ -0,0 +1,287 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+function extractHeadings(content) {
+  const headings = [];
+
+  const htmlMatches = content.matchAll(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gim);
+  for (const match of htmlMatches) {
+    headings.push({
+      level: Number.parseInt(match[1], 10),
+      text: match[2].replace(/<[^>]+>/g, "").trim(),
+      source: "html"
+    });
+  }
+
+  if (headings.length === 0) {
+    const mdMatches = content.matchAll(/^(#{1,6})\s+(.+)$/gm);
+    for (const match of mdMatches) {
+      headings.push({
+        level: match[1].length,
+        text: match[2].trim(),
+        source: "markdown"
+      });
+    }
+  }
+
+  return headings;
+}
+
+function analyzeHierarchy(headings) {
+  const issues = [];
+  const levels = headings.map((h) => h.level);
+
+  if (levels.length === 0) {
+    return { issues: [{ severity: "error", message: "No headings found" }], depth: 0, levelDistribution: {} };
+  }
+
+  const h1Count = levels.filter((l) => l === 1).length;
+  if (h1Count === 0) {
+    issues.push({ severity: "error", message: "Missing H1 heading" });
+  } else if (h1Count > 1) {
+    issues.push({ severity: "warning", message: `Multiple H1 headings found (${h1Count}). Best practice: use only one H1.` });
+  }
+
+  if (levels[0] !== 1) {
+    issues.push({ severity: "warning", message: `First heading is H${levels[0]}, should be H1` });
+  }
+
+  for (let i = 1; i < levels.length; i++) {
+    if (levels[i] > levels[i - 1] + 1) {
+      issues.push({
+        severity: "warning",
+        message: `Skipped heading level: H${levels[i - 1]} → H${levels[i]} at "${headings[i].text.slice(0, 40)}"`
+      });
+    }
+  }
+
+  const usedLevels = new Set(levels);
+  const maxLevel = Math.max(...levels);
+  for (let l = 1; l <= maxLevel; l++) {
+    if (!usedLevels.has(l)) {
+      issues.push({ severity: "info", message: `H${l} level not used (gap in hierarchy)` });
+    }
+  }
+
+  const depth = Math.max(...levels);
+  const levelDistribution = {};
+  for (let l = 1; l <= 6; l++) {
+    levelDistribution[`h${l}`] = levels.filter((lev) => lev === l).length;
+  }
+
+  return { issues, depth, levelDistribution };
+}
+
+function analyzeSemanticCoverage(headings) {
+  const texts = headings.map((h) => h.text.toLowerCase());
+  const fullText = texts.join(" ");
+
+  const categories = {
+    what: { pattern: /\b(what|definition|overview|introduction|about|summary)\b/i, found: false },
+    how: { pattern: /\b(how|guide|tutorial|steps?|instructions?|process|method)\b/i, found: false },
+    why: { pattern: /\b(why|benefits?|advantages?|reasons?|importance|value)\b/i, found: false },
+    who: { pattern: /\b(who|audience|for|users?|customers?|team)\b/i, found: false },
+    comparison: { pattern: /\b(vs\.?|versus|compare|comparison|alternatives?|difference)\b/i, found: false },
+    faq: { pattern: /\b(faq|questions?|q&a)\b|\?/i, found: false },
+    pricing: { pattern: /\b(pricing|cost|plans?|subscription|free|trial)\b/i, found: false },
+    technical: { pattern: /\b(api|sdk|integration|install|setup|configuration|requirements)\b/i, found: false }
+  };
+
+  for (const [key, category] of Object.entries(categories)) {
+    category.found = texts.some((t) => category.pattern.test(t));
+  }
+
+  const covered = Object.values(categories).filter((c) => c.found).length;
+  const total = Object.keys(categories).length;
+
+  return {
+    categories: Object.fromEntries(
+      Object.entries(categories).map(([key, cat]) => [key, cat.found])
+    ),
+    coverageRatio: Math.round((covered / total) * 100),
+    covered,
+    total
+  };
+}
+
+function analyzeQuestionHeadings(headings) {
+  const questions = headings.filter((h) =>
+    h.text.includes("?") || h.text.includes("？") ||
+    /^(what|how|why|when|where|who|which|can|do|does|is|are|should|will)\b/i.test(h.text)
+  );
+
+  return {
+    count: questions.length,
+    ratio: headings.length > 0 ? Math.round((questions.length / headings.length) * 100) : 0,
+    examples: questions.slice(0, 5).map((h) => h.text)
+  };
+}
+
+function computeScore(headings, hierarchy, semanticCoverage, questionHeadings) {
+  if (headings.length === 0) return 0;
+
+  let score = 0;
+  const errors = hierarchy.issues.filter((i) => i.severity === "error");
+  const warnings = hierarchy.issues.filter((i) => i.severity === "warning");
+
+  // Base: heading count
+  score += Math.min(headings.length * 5, 25);
+
+  // Hierarchy quality
+  score += errors.length === 0 ? 25 : (errors.length === 1 ? 10 : 0);
+  score -= warnings.length * 3;
+
+  // Semantic coverage
+  score += Math.round(semanticCoverage.coverageRatio * 0.3);
+
+  // Question headings
+  score += Math.min(questionHeadings.count * 5, 20);
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function buildRecommendations(headings, hierarchy, semanticCoverage, questionHeadings) {
+  const recs = [];
+
+  if (headings.length === 0) {
+    recs.push("Add headings to structure your content. Start with one H1, then use H2s for main sections.");
+    return recs;
+  }
+
+  for (const issue of hierarchy.issues.filter((i) => i.severity === "error")) {
+    recs.push(issue.message);
+  }
+
+  if (headings.length < 3) {
+    recs.push("Add more headings. Content with 5+ headings is easier for AI to parse and cite.");
+  }
+
+  if (questionHeadings.count === 0) {
+    recs.push("Add question-style headings (e.g., 'What is X?', 'How does Y work?') for better AI answer extraction.");
+  }
+
+  const uncovered = Object.entries(semanticCoverage.categories)
+    .filter(([, found]) => !found)
+    .map(([key]) => key);
+
+  if (uncovered.length > 4) {
+    recs.push(`Consider adding sections for: ${uncovered.slice(0, 4).join(", ")} to improve topic coverage.`);
+  }
+
+  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 analyzeHeadingStructure(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 headings = extractHeadings(content);
+  const hierarchy = analyzeHierarchy(headings);
+  const semanticCoverage = analyzeSemanticCoverage(headings);
+  const questionHeadings = analyzeQuestionHeadings(headings);
+  const score = computeScore(headings, hierarchy, semanticCoverage, questionHeadings);
+  const recommendations = buildRecommendations(headings, hierarchy, semanticCoverage, questionHeadings);
+
+  return {
+    kind: "geo-heading-structure",
+    source,
+    headingCount: headings.length,
+    headings: headings.map((h) => ({ level: h.level, text: h.text })),
+    hierarchy,
+    semanticCoverage,
+    questionHeadings,
+    score,
+    scoreLabel: score >= 70 ? "Good" : score >= 40 ? "Fair" : "Needs work",
+    recommendations,
+    summary: `${headings.length} headings, depth ${hierarchy.depth}. Semantic coverage: ${semanticCoverage.coverageRatio}%. Question headings: ${questionHeadings.count}.`
+  };
+}
+
+export function renderHeadingStructureMarkdown(report) {
+  const lines = [
+    "# Heading Structure Analysis",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Total headings: \`${report.headingCount}\``,
+    `- Max depth: \`H${report.hierarchy.depth || 0}\``,
+    `- Summary: ${report.summary}`,
+    "",
+    "## Heading Outline",
+    ""
+  ];
+
+  if (report.headings.length === 0) {
+    lines.push("- No headings found.");
+  } else {
+    for (const h of report.headings) {
+      const indent = "  ".repeat(h.level - 1);
+      lines.push(`${indent}- H${h.level}: ${h.text}`);
+    }
+  }
+
+  lines.push("", "## Level Distribution", "");
+  for (const [level, count] of Object.entries(report.hierarchy.levelDistribution || {})) {
+    if (count > 0) {
+      lines.push(`- ${level.toUpperCase()}: \`${count}\``);
+    }
+  }
+
+  lines.push("", "## Semantic Coverage", "");
+  for (const [category, found] of Object.entries(report.semanticCoverage.categories || {})) {
+    const icon = found ? "✅" : "❌";
+    lines.push(`- ${icon} ${category}`);
+  }
+  lines.push(``, `Coverage: \`${report.semanticCoverage.coverageRatio}%\``);
+
+  if (report.questionHeadings.count > 0) {
+    lines.push("", "## Question Headings", "");
+    for (const q of report.questionHeadings.examples) {
+      lines.push(`- ${q}`);
+    }
+  }
+
+  if (report.hierarchy.issues.length > 0) {
+    lines.push("", "## Hierarchy Issues", "");
+    for (const issue of report.hierarchy.issues) {
+      const icon = issue.severity === "error" ? "❌" : issue.severity === "warning" ? "⚠️" : "ℹ️";
+      lines.push(`- ${icon} ${issue.message}`);
+    }
+  }
+
+  lines.push("", "## Recommendations", "");
+  if (report.recommendations.length === 0) {
+    lines.push("- Heading structure is well-optimized.");
+  } else {
+    for (const rec of report.recommendations) {
+      lines.push(`- ${rec}`);
+    }
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function writeHeadingStructureOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}