@rankcli/agent-runtime 0.0.1 → 0.0.3

package/dist/index.js

@@ -853,6 +853,7 @@ __export(index_exports, {
   applyFixes: () => applyFixes,
   buildGSCApiRequest: () => buildGSCApiRequest,
   buildGSCRequest: () => buildGSCRequest,
+  calculateAIVisibilityScore: () => calculateAIVisibilityScore,
   calculateBM25: () => calculateBM252,
   calculateKeywordTFIDF: () => calculateTFIDF,
   calculateNextRun: () => calculateNextRun,
@@ -867,6 +868,7 @@ __export(index_exports, {
   checkGitHubCLI: () => checkGitHubCLI,
   checkInternalRedirects: () => checkInternalRedirects,
   checkJSRenderingRatio: () => checkJSRenderingRatio,
+  checkLLMCitations: () => checkLLMCitations,
   checkLlmsTxt: () => checkLlmsTxt,
   checkMobileResources: () => checkMobileResources,
   checkPlaintextEmails: () => checkPlaintextEmails,
@@ -970,6 +972,7 @@ __export(index_exports, {
   generatePDFReport: () => generatePDFReport,
   generatePRDescription: () => generatePRDescription,
   generateReactHelmetSocialMeta: () => generateReactHelmetSocialMeta,
+  generateRecommendationQueries: () => generateRecommendationQueries,
   generateRemixMeta: () => generateRemixMeta,
   generateSecretsDoc: () => generateSecretsDoc,
   generateSocialMetaFix: () => generateSocialMetaFix,
@@ -977,6 +980,7 @@ __export(index_exports, {
   generateUncertaintyQuestions: () => generateUncertaintyQuestions,
   generateWizardQuestions: () => generateWizardQuestions,
   generateWorkflow: () => generateWorkflow,
+  getAIVisibilitySummary: () => getAIVisibilitySummary,
   getAutocompleteSuggestions: () => getAutocompleteSuggestions,
   getDateRange: () => getDateRange,
   getExpandedSuggestions: () => getExpandedSuggestions,
@@ -1321,6 +1325,15 @@ var ISSUE_DEFINITIONS = {
     impact: "Poor user experience and potential trust issues.",
     howToFix: "Update or remove the broken external link."
   },
+  JS_ONLY_NAVIGATION: {
+    code: "JS_ONLY_NAVIGATION",
+    severity: "warning",
+    category: "links",
+    title: "JavaScript-only navigation detected",
+    description: "Navigation elements use onClick handlers without proper <a href> links.",
+    impact: "Search engine crawlers cannot follow JavaScript-only navigation. These links are invisible to crawlers, preventing page discovery and indexing.",
+    howToFix: "Replace onClick navigation with proper <a href> or <Link> components. In React, use react-router Link instead of navigate() in onClick handlers. Ensure all navigation renders as real anchor tags with href attributes."
+  },
   TOO_MANY_LINKS: {
     code: "TOO_MANY_LINKS",
     severity: "notice",
@@ -3183,6 +3196,7 @@ async function analyzeLinks(html, baseUrl, checkBroken = false) {
   const external = [];
   const brokenInternal = [];
   const brokenExternal = [];
+  const jsOnlyNavigation = [];
   $("a[href]").each((_, el) => {
     const href = $(el).attr("href") || "";
     const text = $(el).text().trim();
@@ -3211,6 +3225,56 @@ async function analyzeLinks(html, baseUrl, checkBroken = false) {
     }
   });
   const totalLinks = internal.length + external.length;
+  const navPatterns = /navigate|router|history\.push|location\.href|window\.location|goto|redirect/i;
+  const navTextPatterns = /^(home|about|contact|pricing|blog|docs|features|products?|services?|sign\s*up|log\s*in|register|dashboard|account|settings|help|faq|support|menu|nav)$/i;
+  $("button[onclick], div[onclick], span[onclick], li[onclick]").each((_, el) => {
+    const $el = $(el);
+    const onclick = $el.attr("onclick") || "";
+    const text = $el.text().trim().substring(0, 50);
+    if (navPatterns.test(onclick) || navTextPatterns.test(text)) {
+      jsOnlyNavigation.push({
+        element: el.tagName.toLowerCase(),
+        text: text || "(no text)",
+        reason: "Element uses onClick for navigation instead of <a href>"
+      });
+    }
+  });
+  $("a[onclick]").each((_, el) => {
+    const $el = $(el);
+    const href = $el.attr("href") || "";
+    const onclick = $el.attr("onclick") || "";
+    const text = $el.text().trim().substring(0, 50);
+    if ((href === "#" || href === "" || href.startsWith("javascript:")) && onclick) {
+      jsOnlyNavigation.push({
+        element: "a",
+        text: text || "(no text)",
+        reason: `Link has href="${href}" with onClick - crawlers cannot follow this`
+      });
+    }
+  });
+  $("[data-href], [data-to], [data-link], [data-route]").each((_, el) => {
+    const $el = $(el);
+    const tagName = el.tagName.toLowerCase();
+    const text = $el.text().trim().substring(0, 50);
+    if (tagName !== "a" || !$el.attr("href") || $el.attr("href") === "#") {
+      jsOnlyNavigation.push({
+        element: tagName,
+        text: text || "(no text)",
+        reason: "Uses data attribute for routing instead of real href"
+      });
+    }
+  });
+  if (jsOnlyNavigation.length > 0) {
+    const uniqueNav = jsOnlyNavigation.slice(0, 10);
+    issues.push({
+      ...ISSUE_DEFINITIONS.JS_ONLY_NAVIGATION,
+      affectedUrls: [baseUrl],
+      details: {
+        count: jsOnlyNavigation.length,
+        examples: uniqueNav
+      }
+    });
+  }
   const internalCount = internal.length;
   const externalCount = external.length;
   const internalToExternalRatio = externalCount > 0 ? internalCount / externalCount : null;
@@ -3318,6 +3382,7 @@ async function analyzeLinks(html, baseUrl, checkBroken = false) {
       totalLinks,
       brokenInternal,
       brokenExternal,
+      jsOnlyNavigation,
       ratio: {
         internal: internalCount,
         external: externalCount,
@@ -8693,6 +8758,12 @@ function analyzeContentScience(html, url, targetKeywords = []) {
 init_http();
 var cheerio28 = __toESM(require("cheerio"));
 async function getSSLCertificateAge(url) {
+  let https;
+  try {
+    https = await import("https");
+  } catch {
+    return null;
+  }
   return new Promise((resolve) => {
     try {
       const parsedUrl = new URL(url);
@@ -15210,7 +15281,7 @@ var cheerio49 = __toESM(require("cheerio"));
 init_http();
 async function analyzeHtmlCompliance(html, url, headers) {
   const issues = [];
-  const $ = cheerio49.load(html, { decodeEntities: false });
+  const $ = cheerio49.load(html);
   const parsedUrl = new URL(url);
   const doctypeMatch = html.match(/<!DOCTYPE\s+([^>]+)>/i);
   const hasDoctype = doctypeMatch !== null;
@@ -26679,26 +26750,104 @@ async function generateFixForIssue(issue, context) {
   const fullUrl = url || "https://example.com";
   const siteName = new URL(fullUrl).hostname.replace("www.", "");
   switch (issue.code) {
+    // Title issues
     case "MISSING_TITLE":
+    case "TITLE_MISSING":
+    // Full audit code
+    case "TITLE_KEYWORD_MISMATCH":
+    case "TITLE_H1_KEYWORD_MISMATCH":
+    case "OUTDATED_YEAR_IN_TITLE":
       return generateTitleFix(context, siteName);
+    // Meta description issues
     case "MISSING_META_DESC":
+    case "META_DESC_MISSING":
       return generateMetaDescFix(context, siteName);
+    // Canonical issues
     case "MISSING_CANONICAL":
+    case "CANONICAL_NO_HTTPS_REDIRECT":
       return generateCanonicalFix(context, fullUrl);
+    // Viewport issues
     case "MISSING_VIEWPORT":
+    case "HTML_NO_VIEWPORT":
+    case "RESPONSIVE_NO_VIEWPORT":
       return generateViewportFix(context);
+    // Open Graph issues
     case "MISSING_OG_TAGS":
+    case "OG_TITLE_MISSING":
+    case "OG_DESC_MISSING":
+    case "OG_IMAGE_MISSING":
+    case "OG_URL_MISSING":
       return generateOGFix(context, siteName, fullUrl);
+    // Twitter Card issues
     case "MISSING_TWITTER_CARD":
+    case "TWITTER_CARD_MISSING":
+    case "TWITTER_TITLE_MISSING":
+    case "TWITTER_DESC_MISSING":
+    case "TWITTER_IMAGE_MISSING":
       return generateTwitterFix(context, siteName);
+    // Schema/structured data issues
     case "MISSING_SCHEMA":
+    case "SCHEMA_MISSING":
+    // Full audit code
+    case "SCHEMA_ORG_MISSING":
+    case "NO_ORGANIZATION_SCHEMA":
+    case "NO_ENTITY_SCHEMA":
+    case "FAQ_SCHEMA_MISSING":
       return generateSchemaFix(context, siteName, fullUrl);
+    // Robots.txt issues
     case "MISSING_ROBOTS":
+    case "ROBOTS_TXT_MISSING":
+    // Full audit code
+    case "ROBOTS_TXT_WARNINGS":
+    case "ROBOTS_TXT_INVALID_SYNTAX":
       return generateRobotsFix(context, fullUrl);
+    // Sitemap issues
     case "MISSING_SITEMAP":
+    case "SITEMAP_MISSING":
+    // Full audit code
+    case "BING_SITEMAP_MISSING":
       return generateSitemapFix(context, fullUrl);
+    // H1 issues
     case "MISSING_H1":
+    case "NO_VISIBLE_HEADLINE":
+    case "H1_MISSING_KEYWORD":
       return await generateH1Fix({ cwd });
+    // SPA-specific: add meta management library recommendation
+    case "SPA_NO_META_MANAGEMENT":
+    case "SPA_WITHOUT_SSR":
+    case "CLIENT_SIDE_RENDERING":
+      return generateSPAMetaFix(context, framework);
+    // Internal links - suggest adding links
+    case "NO_INTERNAL_LINKS":
+    case "LINKS_NO_INTERNAL":
+    case "NO_CONTENT_INTERNAL_LINKS":
+      return {
+        issue: { code: issue.code, message: "No internal links found", severity: "warning" },
+        file: "src/components/Footer.tsx",
+        before: null,
+        after: `// Add internal navigation links to your footer or content
+// Example: <Link to="/about">About</Link>`,
+        explanation: "Add internal links to help search engines discover your content",
+        skipped: true,
+        skipReason: "Requires manual content updates - add links to your navigation and content"
+      };
+    // Preconnect issues
+    case "GOOGLE_FONTS_NO_PRECONNECT":
+    case "MISSING_PRECONNECT":
+      return generatePreconnectFix(context);
+    // Favicon/icons
+    case "HTML_NO_FAVICON":
+    case "HTML_NO_APPLE_TOUCH_ICON":
+      return generateFaviconFix(context);
+    // Charset/lang
+    case "HTML_NO_CHARSET":
+    case "HTML_NOT_UTF8":
+      return generateCharsetFix(context);
+    case "HTML_NO_LANG":
+      return generateLangFix(context);
+    // AI/LLMs.txt
+    case "AI_NO_LLMS_TXT":
+      return generateLlmsTxtFix(context, siteName, fullUrl);
     default:
       return null;
   }
@@ -26927,6 +27076,159 @@ function generateSitemapFix(context, url) {
     explanation: "Created sitemap.xml to help search engines discover all pages"
   };
 }
+function generateSPAMetaFix(context, framework) {
+  const { htmlPath } = context;
+  if (framework.name.toLowerCase().includes("react") || framework.name === "Unknown") {
+    return {
+      issue: { code: "SPA_NO_META_MANAGEMENT", message: "SPA without dynamic meta tag management", severity: "warning" },
+      file: "src/components/SEOHead.tsx",
+      before: null,
+      after: `import { Helmet } from 'react-helmet-async';
+
+interface SEOHeadProps {
+  title?: string;
+  description?: string;
+  image?: string;
+  url?: string;
+}
+
+export function SEOHead({ 
+  title = 'Your Site Name',
+  description = 'Your site description',
+  image = '/og-image.png',
+  url = window.location.href,
+}: SEOHeadProps) {
+  return (
+    <Helmet>
+      <title>{title}</title>
+      <meta name="description" content={description} />
+      <link rel="canonical" href={url} />
+      
+      {/* Open Graph */}
+      <meta property="og:title" content={title} />
+      <meta property="og:description" content={description} />
+      <meta property="og:image" content={image} />
+      <meta property="og:url" content={url} />
+      <meta property="og:type" content="website" />
+      
+      {/* Twitter */}
+      <meta name="twitter:card" content="summary_large_image" />
+      <meta name="twitter:title" content={title} />
+      <meta name="twitter:description" content={description} />
+      <meta name="twitter:image" content={image} />
+    </Helmet>
+  );
+}`,
+      explanation: "Created SEOHead component using react-helmet-async for dynamic meta tags. Install: npm install react-helmet-async"
+    };
+  }
+  return {
+    issue: { code: "SPA_NO_META_MANAGEMENT", message: "SPA without meta management", severity: "warning" },
+    file: htmlPath,
+    before: null,
+    after: "<!-- Add a meta management library for your framework -->",
+    explanation: `Add dynamic meta tag management for ${framework.name}`,
+    skipped: true,
+    skipReason: `Framework-specific solution needed for ${framework.name}`
+  };
+}
+function generatePreconnectFix(context) {
+  const { htmlPath, htmlContent } = context;
+  const preconnects = `<!-- Preconnect to external origins -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />`;
+  return {
+    issue: { code: "MISSING_PRECONNECT", message: "Missing preconnect hints", severity: "info" },
+    file: htmlPath,
+    before: "<head>",
+    after: `<head>
+    ${preconnects}`,
+    explanation: "Added preconnect hints to speed up loading of external resources"
+  };
+}
+function generateFaviconFix(context) {
+  const { htmlPath } = context;
+  const faviconTags = `<!-- Favicons -->
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />`;
+  return {
+    issue: { code: "HTML_NO_FAVICON", message: "Missing favicon", severity: "info" },
+    file: htmlPath,
+    before: "<head>",
+    after: `<head>
+    ${faviconTags}`,
+    explanation: "Added favicon links. Create favicon files in public/ directory."
+  };
+}
+function generateCharsetFix(context) {
+  const { htmlPath, htmlContent } = context;
+  if (htmlContent.includes("charset")) {
+    return {
+      issue: { code: "HTML_NO_CHARSET", message: "Missing charset", severity: "warning" },
+      file: htmlPath,
+      before: null,
+      after: '<meta charset="UTF-8" />',
+      skipped: true,
+      skipReason: "Charset already defined",
+      explanation: "Charset is already present"
+    };
+  }
+  return {
+    issue: { code: "HTML_NO_CHARSET", message: "Missing charset declaration", severity: "warning" },
+    file: htmlPath,
+    before: "<head>",
+    after: '<head>\n    <meta charset="UTF-8" />',
+    explanation: "Added UTF-8 charset declaration as first element in head"
+  };
+}
+function generateLangFix(context) {
+  const { htmlPath, htmlContent } = context;
+  if (htmlContent.includes("<html") && !htmlContent.includes("lang=")) {
+    return {
+      issue: { code: "HTML_NO_LANG", message: "Missing lang attribute", severity: "warning" },
+      file: htmlPath,
+      before: "<html>",
+      after: '<html lang="en">',
+      explanation: "Added lang attribute for accessibility and SEO"
+    };
+  }
+  return {
+    issue: { code: "HTML_NO_LANG", message: "Missing lang attribute", severity: "warning" },
+    file: htmlPath,
+    before: "<html",
+    after: '<html lang="en"',
+    explanation: "Added lang attribute for accessibility and SEO"
+  };
+}
+function generateLlmsTxtFix(context, siteName, url) {
+  const llmsTxt = `# ${siteName}
+> ${siteName} - A brief description of your product/service
+
+## About
+${siteName} is... [Add your description here]
+
+## Features
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Links
+- Homepage: ${url}
+- Documentation: ${url}/docs
+- API: ${url}/api
+
+## Contact
+- Email: hello@${new URL(url).hostname}
+`;
+  return {
+    issue: { code: "AI_NO_LLMS_TXT", message: "No llms.txt file for AI crawlers", severity: "info" },
+    file: "public/llms.txt",
+    before: null,
+    after: llmsTxt,
+    explanation: "Created llms.txt to help AI systems understand your site. Customize the content."
+  };
+}
 async function applyFixes(fixes, options) {
   const { cwd, dryRun = false } = options;
   const applied = [];
@@ -28725,6 +29027,105 @@ function escapeRegex2(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// src/geo/llm-citation-checker.ts
+var PROVIDER_NAMES = {
+  openai: "ChatGPT",
+  anthropic: "Claude",
+  google: "Gemini",
+  perplexity: "Perplexity"
+};
+var DEFAULT_PROVIDERS = ["openai", "anthropic", "google", "perplexity"];
+function generateRecommendationQueries(brand, industry) {
+  const queries = [
+    `What are the best ${brand.toLowerCase()} alternatives?`,
+    `Can you recommend tools similar to ${brand}?`,
+    `What do you think about ${brand}?`
+  ];
+  if (industry) {
+    queries.push(`What are the best ${industry} tools?`);
+    queries.push(`Recommend a good ${industry} solution`);
+  }
+  return queries;
+}
+async function checkLLMCitations(brand, domain, options = {}) {
+  const {
+    providers = DEFAULT_PROVIDERS,
+    queries = generateRecommendationQueries(brand),
+    ...trackingOptions
+  } = options;
+  const brandConfig = {
+    brandName: brand,
+    domains: [domain],
+    alternativeNames: [brand.toLowerCase(), brand.toUpperCase()]
+  };
+  const query = queries[0];
+  const results = await trackLLMVisibility(
+    {
+      keyword: query,
+      brand: brandConfig,
+      providers
+    },
+    trackingOptions
+  );
+  return results.map((result) => ({
+    provider: result.provider,
+    providerName: PROVIDER_NAMES[result.provider],
+    mentioned: result.mentioned,
+    position: result.position,
+    sentiment: result.sentiment,
+    context: result.contextSnippet || null,
+    score: result.score,
+    error: result.error
+  }));
+}
+function calculateAIVisibilityScore(results) {
+  if (results.length === 0) return 0;
+  const mentionedCount = results.filter((r) => r.mentioned && !r.error).length;
+  const validResults = results.filter((r) => !r.error);
+  if (validResults.length === 0) return 0;
+  let score = mentionedCount / validResults.length * 100;
+  const topPositions = results.filter(
+    (r) => r.mentioned && r.position !== null && r.position <= 3
+  );
+  if (topPositions.length > 0) {
+    score = Math.min(100, score + 10);
+  }
+  const positiveResults = results.filter((r) => r.sentiment === "positive");
+  if (positiveResults.length > mentionedCount / 2) {
+    score = Math.min(100, score + 5);
+  }
+  return Math.round(score);
+}
+function getAIVisibilitySummary(results) {
+  const score = calculateAIVisibilityScore(results);
+  const mentionedIn = results.filter((r) => r.mentioned).map((r) => r.providerName);
+  const notMentionedIn = results.filter((r) => !r.mentioned && !r.error).map((r) => r.providerName);
+  const positions = results.filter((r) => r.position !== null).map((r) => r.position);
+  const bestPosition = positions.length > 0 ? Math.min(...positions) : null;
+  const sentiments = results.filter((r) => r.sentiment !== null).map((r) => r.sentiment);
+  let overallSentiment = null;
+  if (sentiments.length > 0) {
+    const positiveCount = sentiments.filter((s) => s === "positive").length;
+    const negativeCount = sentiments.filter((s) => s === "negative").length;
+    if (positiveCount > 0 && negativeCount > 0) {
+      overallSentiment = "mixed";
+    } else if (positiveCount > negativeCount) {
+      overallSentiment = "positive";
+    } else if (negativeCount > positiveCount) {
+      overallSentiment = "negative";
+    } else {
+      overallSentiment = "neutral";
+    }
+  }
+  return {
+    score,
+    mentionedIn,
+    notMentionedIn,
+    bestPosition,
+    overallSentiment
+  };
+}
+
 // src/frameworks/index.ts
 var frameworks_exports = {};
 __export(frameworks_exports, {
@@ -29481,6 +29882,7 @@ if (typeof globalThis !== "undefined") {
   applyFixes,
   buildGSCApiRequest,
   buildGSCRequest,
+  calculateAIVisibilityScore,
   calculateBM25,
   calculateKeywordTFIDF,
   calculateNextRun,
@@ -29495,6 +29897,7 @@ if (typeof globalThis !== "undefined") {
   checkGitHubCLI,
   checkInternalRedirects,
   checkJSRenderingRatio,
+  checkLLMCitations,
   checkLlmsTxt,
   checkMobileResources,
   checkPlaintextEmails,
@@ -29598,6 +30001,7 @@ if (typeof globalThis !== "undefined") {
   generatePDFReport,
   generatePRDescription,
   generateReactHelmetSocialMeta,
+  generateRecommendationQueries,
   generateRemixMeta,
   generateSecretsDoc,
   generateSocialMetaFix,
@@ -29605,6 +30009,7 @@ if (typeof globalThis !== "undefined") {
   generateUncertaintyQuestions,
   generateWizardQuestions,
   generateWorkflow,
+  getAIVisibilitySummary,
   getAutocompleteSuggestions,
   getDateRange,
   getExpandedSuggestions,