geo-ai-search-optimization 2.0.0 → 2.2.0

package/src/validate-schema.js

@@ -0,0 +1,306 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeScanOutput } from "./scan.js";
+
+const REQUIRED_FIELDS = {
+  Organization: ["name", "url"],
+  Corporation: ["name", "url"],
+  LocalBusiness: ["name", "url", "address"],
+  Person: ["name"],
+  Article: ["headline", "author", "datePublished"],
+  BlogPosting: ["headline", "author", "datePublished"],
+  NewsArticle: ["headline", "author", "datePublished", "dateModified"],
+  FAQPage: ["mainEntity"],
+  HowTo: ["name", "step"],
+  Product: ["name"],
+  SoftwareApplication: ["name"],
+  BreadcrumbList: ["itemListElement"],
+  WebSite: ["name", "url"],
+  WebPage: ["name"]
+};
+
+const AI_DISCOVERABILITY_FIELDS = {
+  Organization: ["sameAs", "logo", "description", "foundingDate", "numberOfEmployees"],
+  Person: ["sameAs", "jobTitle", "worksFor", "url"],
+  Article: ["dateModified", "publisher", "image", "description", "mainEntityOfPage"],
+  BlogPosting: ["dateModified", "publisher", "image", "description", "mainEntityOfPage"],
+  Product: ["brand", "offers", "description", "image", "aggregateRating"],
+  FAQPage: [],
+  BreadcrumbList: [],
+  WebSite: ["potentialAction", "description"],
+  HowTo: ["description", "totalTime", "image"]
+};
+
+const SPEAKABLE_ELIGIBLE = new Set(["Article", "BlogPosting", "NewsArticle", "WebPage"]);
+
+function extractJsonLd(html) {
+  const blocks = [];
+  const regex = /<script[^>]*type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+  let match;
+
+  while ((match = regex.exec(html)) !== null) {
+    try {
+      const parsed = JSON.parse(match[1].trim());
+      if (Array.isArray(parsed)) {
+        blocks.push(...parsed);
+      } else {
+        blocks.push(parsed);
+      }
+    } catch {
+      blocks.push({ _parseError: true, _raw: match[1].trim().slice(0, 200) });
+    }
+  }
+
+  return blocks;
+}
+
+function flattenGraph(blocks) {
+  const flat = [];
+  for (const block of blocks) {
+    if (block["@graph"] && Array.isArray(block["@graph"])) {
+      flat.push(...block["@graph"]);
+    } else {
+      flat.push(block);
+    }
+  }
+  return flat;
+}
+
+function getType(entity) {
+  const raw = entity["@type"];
+  if (Array.isArray(raw)) return raw[0];
+  return raw || "Unknown";
+}
+
+function validateEntity(entity) {
+  const type = getType(entity);
+  const issues = [];
+  const warnings = [];
+  const enhancements = [];
+
+  if (entity._parseError) {
+    return {
+      type: "ParseError",
+      issues: [{ field: "_raw", message: "Failed to parse JSON-LD block", severity: "error" }],
+      warnings: [],
+      enhancements: []
+    };
+  }
+
+  if (!entity["@context"] || !String(entity["@context"]).includes("schema.org")) {
+    issues.push({ field: "@context", message: "Missing or invalid @context (should be https://schema.org)", severity: "error" });
+  }
+
+  if (!entity["@type"]) {
+    issues.push({ field: "@type", message: "Missing @type", severity: "error" });
+  }
+
+  const required = REQUIRED_FIELDS[type] || [];
+  for (const field of required) {
+    if (!entity[field] && entity[field] !== 0) {
+      issues.push({ field, message: `Missing required field: ${field}`, severity: "error" });
+    }
+  }
+
+  const aiFields = AI_DISCOVERABILITY_FIELDS[type] || [];
+  for (const field of aiFields) {
+    if (!entity[field]) {
+      enhancements.push({ field, message: `Add ${field} for better AI discoverability`, severity: "enhancement" });
+    }
+  }
+
+  if (SPEAKABLE_ELIGIBLE.has(type) && !entity.speakable) {
+    enhancements.push({ field: "speakable", message: "Add speakable property for voice search and AI reading", severity: "enhancement" });
+  }
+
+  if (entity.sameAs) {
+    const sameAs = Array.isArray(entity.sameAs) ? entity.sameAs : [entity.sameAs];
+    for (const url of sameAs) {
+      try {
+        new URL(url);
+      } catch {
+        warnings.push({ field: "sameAs", message: `Invalid sameAs URL: ${url}`, severity: "warning" });
+      }
+    }
+  }
+
+  if (entity.datePublished && !/^\d{4}-\d{2}-\d{2}/.test(entity.datePublished)) {
+    warnings.push({ field: "datePublished", message: "datePublished should be in ISO 8601 format (YYYY-MM-DD)", severity: "warning" });
+  }
+
+  if (entity.dateModified && !/^\d{4}-\d{2}-\d{2}/.test(entity.dateModified)) {
+    warnings.push({ field: "dateModified", message: "dateModified should be in ISO 8601 format (YYYY-MM-DD)", severity: "warning" });
+  }
+
+  return { type, issues, warnings, enhancements };
+}
+
+function computeScore(validations) {
+  if (validations.length === 0) return 0;
+
+  let totalErrors = 0;
+  let totalWarnings = 0;
+  let totalEnhancements = 0;
+
+  for (const v of validations) {
+    totalErrors += v.issues.length;
+    totalWarnings += v.warnings.length;
+    totalEnhancements += v.enhancements.length;
+  }
+
+  let score = 100;
+  score -= totalErrors * 12;
+  score -= totalWarnings * 5;
+  score -= totalEnhancements * 2;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+function getScoreLabel(score) {
+  if (score >= 90) return "Excellent";
+  if (score >= 70) return "Good";
+  if (score >= 50) return "Needs work";
+  return "Poor";
+}
+
+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 validateSchema(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;
+
+    if (filePath.endsWith(".json")) {
+      try {
+        const parsed = JSON.parse(content);
+        const entities = Array.isArray(parsed) ? parsed : [parsed];
+        const flat = flattenGraph(entities);
+        const validations = flat.map(validateEntity);
+        const score = computeScore(validations);
+
+        return {
+          kind: "geo-validate-schema",
+          source,
+          entityCount: flat.length,
+          types: flat.map(getType),
+          validations,
+          score,
+          scoreLabel: getScoreLabel(score),
+          summary: buildSummary(validations, score)
+        };
+      } catch {
+        // Not valid JSON, treat as HTML
+      }
+    }
+  }
+
+  const blocks = extractJsonLd(content);
+  const flat = flattenGraph(blocks);
+
+  if (flat.length === 0) {
+    return {
+      kind: "geo-validate-schema",
+      source,
+      entityCount: 0,
+      types: [],
+      validations: [],
+      score: 0,
+      scoreLabel: "No schema found",
+      summary: "No JSON-LD structured data found. Add schema markup with: geo-ai-search-optimization init-schema <type>"
+    };
+  }
+
+  const validations = flat.map(validateEntity);
+  const score = computeScore(validations);
+
+  return {
+    kind: "geo-validate-schema",
+    source,
+    entityCount: flat.length,
+    types: flat.map(getType),
+    validations,
+    score,
+    scoreLabel: getScoreLabel(score),
+    summary: buildSummary(validations, score)
+  };
+}
+
+function buildSummary(validations, score) {
+  const totalErrors = validations.reduce((sum, v) => sum + v.issues.length, 0);
+  const totalWarnings = validations.reduce((sum, v) => sum + v.warnings.length, 0);
+  const totalEnhancements = validations.reduce((sum, v) => sum + v.enhancements.length, 0);
+
+  if (totalErrors === 0 && totalWarnings === 0) {
+    return `Schema validation: ${score}/100. All entities valid.${totalEnhancements > 0 ? ` ${totalEnhancements} enhancement(s) available for AI discoverability.` : ""}`;
+  }
+
+  return `Schema validation: ${score}/100. ${totalErrors} error(s), ${totalWarnings} warning(s), ${totalEnhancements} enhancement(s).`;
+}
+
+export function renderValidateSchemaMarkdown(report) {
+  const lines = [
+    "# Schema Validation Report",
+    "",
+    `- Source: \`${report.source}\``,
+    `- Entities found: \`${report.entityCount}\``,
+    `- Types: ${report.types.map((t) => `\`${t}\``).join(", ") || "none"}`,
+    `- Score: \`${report.score}/100\` (${report.scoreLabel})`,
+    `- Summary: ${report.summary}`,
+    ""
+  ];
+
+  if (report.entityCount === 0) {
+    lines.push("## Action Required", "", "- Add JSON-LD structured data to your pages.", "");
+    return lines.join("\n");
+  }
+
+  for (let i = 0; i < report.validations.length; i++) {
+    const v = report.validations[i];
+    lines.push(`## Entity ${i + 1}: ${v.type}`, "");
+
+    if (v.issues.length > 0) {
+      lines.push("### Errors", "");
+      for (const issue of v.issues) {
+        lines.push(`- ❌ \`${issue.field}\`: ${issue.message}`);
+      }
+      lines.push("");
+    }
+
+    if (v.warnings.length > 0) {
+      lines.push("### Warnings", "");
+      for (const warning of v.warnings) {
+        lines.push(`- ⚠️ \`${warning.field}\`: ${warning.message}`);
+      }
+      lines.push("");
+    }
+
+    if (v.enhancements.length > 0) {
+      lines.push("### AI Discoverability Enhancements", "");
+      for (const enh of v.enhancements) {
+        lines.push(`- 💡 \`${enh.field}\`: ${enh.message}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export async function writeValidateSchemaOutput(outputPath, content) {
+  return writeScanOutput(outputPath, content);
+}