@rankcli/agent-runtime 0.0.1

package/src/content/headline.ts

@@ -0,0 +1,317 @@
+// Headline Analysis & Optimization
+// Scores headlines for SEO and engagement effectiveness
+
+export interface HeadlineAnalysis {
+  headline: string;
+  score: number; // 0-100
+  wordCount: number;
+  charCount: number;
+  // Score breakdown
+  breakdown: {
+    length: number;
+    powerWords: number;
+    emotionalWords: number;
+    numbers: number;
+    readability: number;
+    uniqueness: number;
+  };
+  // Issues and suggestions
+  issues: string[];
+  suggestions: string[];
+  // Classification
+  type: 'how-to' | 'list' | 'question' | 'statement' | 'guide' | 'other';
+  sentiment: 'positive' | 'negative' | 'neutral';
+}
+
+// Power words that drive engagement
+const POWER_WORDS = new Set([
+  'ultimate', 'essential', 'proven', 'powerful', 'incredible', 'amazing',
+  'exclusive', 'secret', 'free', 'new', 'best', 'top', 'complete', 'simple',
+  'easy', 'quick', 'fast', 'instant', 'guaranteed', 'effective', 'brilliant',
+  'stunning', 'remarkable', 'exceptional', 'revolutionary', 'breakthrough',
+  'transform', 'discover', 'unlock', 'master', 'boost', 'skyrocket', 'crush',
+]);
+
+// Emotional trigger words
+const EMOTIONAL_WORDS = new Set([
+  'love', 'hate', 'fear', 'anxiety', 'stress', 'happy', 'sad', 'angry',
+  'frustrated', 'excited', 'thrilled', 'terrified', 'worried', 'confident',
+  'surprising', 'shocking', 'devastating', 'inspiring', 'heartwarming',
+  'painful', 'embarrassing', 'awkward', 'dangerous', 'risky', 'safe',
+]);
+
+// Common/weak words to avoid
+const WEAK_WORDS = new Set([
+  'things', 'stuff', 'very', 'really', 'just', 'actually', 'basically',
+  'literally', 'nice', 'good', 'great', 'awesome', 'cool', 'interesting',
+]);
+
+/**
+ * Analyze headline effectiveness
+ */
+export function analyzeHeadline(headline: string): HeadlineAnalysis {
+  const words = headline.toLowerCase().split(/\s+/).filter(w => w.length > 0);
+  const wordCount = words.length;
+  const charCount = headline.length;
+
+  const issues: string[] = [];
+  const suggestions: string[] = [];
+
+  // Score components
+  const breakdown = {
+    length: 0,
+    powerWords: 0,
+    emotionalWords: 0,
+    numbers: 0,
+    readability: 0,
+    uniqueness: 0,
+  };
+
+  // 1. Length score (ideal: 6-12 words, 50-60 chars for SEO)
+  if (wordCount >= 6 && wordCount <= 12) {
+    breakdown.length = 25;
+  } else if (wordCount >= 4 && wordCount <= 15) {
+    breakdown.length = 15;
+  } else if (wordCount < 4) {
+    breakdown.length = 5;
+    issues.push('Too short - aim for 6-12 words');
+    suggestions.push('Add more descriptive words to convey value');
+  } else {
+    breakdown.length = 10;
+    issues.push('Too long - may get truncated in SERPs');
+    suggestions.push('Trim to under 60 characters for display');
+  }
+
+  if (charCount <= 60) {
+    breakdown.length += 5;
+  } else if (charCount <= 70) {
+    breakdown.length += 2;
+  } else {
+    issues.push(`Title is ${charCount} chars (${charCount - 60} over limit)`);
+  }
+
+  // 2. Power words
+  const powerWordCount = words.filter(w => POWER_WORDS.has(w.replace(/[^a-z]/g, ''))).length;
+  if (powerWordCount >= 2) {
+    breakdown.powerWords = 20;
+  } else if (powerWordCount === 1) {
+    breakdown.powerWords = 15;
+    suggestions.push('Add another power word for more impact');
+  } else {
+    breakdown.powerWords = 0;
+    suggestions.push('Include power words like: ultimate, proven, essential, free');
+  }
+
+  // 3. Emotional words
+  const emotionalCount = words.filter(w => EMOTIONAL_WORDS.has(w.replace(/[^a-z]/g, ''))).length;
+  if (emotionalCount >= 1) {
+    breakdown.emotionalWords = 15;
+  } else {
+    breakdown.emotionalWords = 5;
+    suggestions.push('Consider adding emotional trigger words for engagement');
+  }
+
+  // 4. Numbers (lists perform well)
+  const hasNumber = /\d+/.test(headline);
+  if (hasNumber) {
+    breakdown.numbers = 15;
+    // Odd numbers perform better
+    const numbers = headline.match(/\d+/g) || [];
+    const hasOddNumber = numbers.some(n => parseInt(n) % 2 !== 0);
+    if (hasOddNumber) {
+      breakdown.numbers += 5;
+    }
+  } else {
+    breakdown.numbers = 0;
+    suggestions.push('Consider adding a number (e.g., "7 Ways to...", "5 Tips for...")');
+  }
+
+  // 5. Readability
+  const weakWordCount = words.filter(w => WEAK_WORDS.has(w)).length;
+  if (weakWordCount === 0) {
+    breakdown.readability = 15;
+  } else {
+    breakdown.readability = Math.max(0, 15 - weakWordCount * 5);
+    issues.push(`Contains weak/vague words: ${words.filter(w => WEAK_WORDS.has(w)).join(', ')}`);
+  }
+
+  // Check for sentence case (Title Case vs sentence case)
+  const titleCaseWords = words.filter((w, i) => i > 0 && /^[A-Z]/.test(headline.split(/\s+/)[i]));
+  if (titleCaseWords.length > words.length * 0.7) {
+    suggestions.push('Consider sentence case instead of Title Case for better readability');
+  }
+
+  // 6. Uniqueness (check for clichés)
+  const cliches = [
+    'you need to know',
+    'you won\'t believe',
+    'the truth about',
+    'everything you need',
+    'game changer',
+    'must read',
+  ];
+  const hasCliche = cliches.some(c => headline.toLowerCase().includes(c));
+  if (hasCliche) {
+    breakdown.uniqueness = 5;
+    issues.push('Contains overused phrases/clichés');
+    suggestions.push('Try a more original angle or phrasing');
+  } else {
+    breakdown.uniqueness = 10;
+  }
+
+  // Classify headline type
+  const type = classifyHeadlineType(headline);
+
+  // Determine sentiment
+  const sentiment = analyzeSentiment(words);
+
+  // Calculate total score
+  const score = Math.min(100,
+    breakdown.length +
+    breakdown.powerWords +
+    breakdown.emotionalWords +
+    breakdown.numbers +
+    breakdown.readability +
+    breakdown.uniqueness
+  );
+
+  // Add type-specific suggestions
+  if (type === 'question' && !headline.endsWith('?')) {
+    suggestions.push('Question headlines should end with a question mark');
+  }
+
+  if (type === 'how-to' && !headline.toLowerCase().startsWith('how to')) {
+    suggestions.push('Ensure "How to" appears at the beginning for clarity');
+  }
+
+  return {
+    headline,
+    score,
+    wordCount,
+    charCount,
+    breakdown,
+    issues,
+    suggestions,
+    type,
+    sentiment,
+  };
+}
+
+function classifyHeadlineType(headline: string): HeadlineAnalysis['type'] {
+  const h = headline.toLowerCase();
+
+  if (h.startsWith('how to') || h.includes('how to')) return 'how-to';
+  if (/^\d+\s/.test(h) || /\btop\s+\d+\b/.test(h)) return 'list';
+  if (h.endsWith('?') || h.startsWith('what') || h.startsWith('why') || h.startsWith('when')) return 'question';
+  if (h.includes('guide') || h.includes('tutorial')) return 'guide';
+  if (/^(the|a|an)\s/i.test(h)) return 'statement';
+
+  return 'other';
+}
+
+function analyzeSentiment(words: string[]): HeadlineAnalysis['sentiment'] {
+  const positiveWords = new Set(['best', 'top', 'amazing', 'great', 'success', 'win', 'boost', 'improve', 'easy', 'free', 'new']);
+  const negativeWords = new Set(['worst', 'bad', 'fail', 'mistake', 'avoid', 'stop', 'never', 'wrong', 'problem', 'risk', 'danger']);
+
+  let positiveCount = 0;
+  let negativeCount = 0;
+
+  for (const word of words) {
+    const w = word.replace(/[^a-z]/g, '');
+    if (positiveWords.has(w)) positiveCount++;
+    if (negativeWords.has(w)) negativeCount++;
+  }
+
+  if (positiveCount > negativeCount) return 'positive';
+  if (negativeCount > positiveCount) return 'negative';
+  return 'neutral';
+}
+
+/**
+ * Generate headline variations
+ */
+export function generateHeadlineVariations(topic: string, keywords: string[]): string[] {
+  const variations: string[] = [];
+  const mainKeyword = keywords[0] || topic;
+
+  // How-to format
+  variations.push(`How to ${topic} in ${Math.floor(Math.random() * 5) + 3} Simple Steps`);
+  variations.push(`How to ${topic}: A Complete Guide`);
+
+  // List format (odd numbers perform better)
+  const oddNumbers = [3, 5, 7, 9, 11, 13];
+  const num = oddNumbers[Math.floor(Math.random() * oddNumbers.length)];
+  variations.push(`${num} Proven Ways to ${topic}`);
+  variations.push(`${num} ${mainKeyword} Tips That Actually Work`);
+
+  // Question format
+  variations.push(`What Is ${topic}? Everything You Need to Know`);
+  variations.push(`Why ${topic} Matters More Than Ever in ${new Date().getFullYear()}`);
+
+  // Statement with power words
+  variations.push(`The Ultimate Guide to ${topic}`);
+  variations.push(`${topic}: The Complete ${new Date().getFullYear()} Guide`);
+
+  // Problem/solution
+  variations.push(`${topic} Made Simple: A Beginner's Guide`);
+  variations.push(`Master ${topic} Without the Confusion`);
+
+  return variations;
+}
+
+/**
+ * Format headline analysis report
+ */
+export function formatHeadlineReport(analysis: HeadlineAnalysis): string {
+  const lines: string[] = [];
+
+  lines.push('');
+  lines.push('═'.repeat(60));
+  lines.push('  HEADLINE ANALYSIS');
+  lines.push('═'.repeat(60));
+  lines.push('');
+
+  // Headline and score
+  lines.push(`"${analysis.headline}"`);
+  lines.push('');
+
+  const scoreIcon = analysis.score >= 70 ? '🟢' : analysis.score >= 50 ? '🟡' : '🔴';
+  lines.push(`${scoreIcon} Score: ${analysis.score}/100`);
+  lines.push(`   Type: ${analysis.type} | Sentiment: ${analysis.sentiment}`);
+  lines.push(`   Length: ${analysis.wordCount} words, ${analysis.charCount} chars`);
+  lines.push('');
+
+  // Score breakdown
+  lines.push('📊 SCORE BREAKDOWN');
+  lines.push('─'.repeat(60));
+  lines.push(`  Length:        ${analysis.breakdown.length}/30`);
+  lines.push(`  Power Words:   ${analysis.breakdown.powerWords}/20`);
+  lines.push(`  Emotion:       ${analysis.breakdown.emotionalWords}/15`);
+  lines.push(`  Numbers:       ${analysis.breakdown.numbers}/20`);
+  lines.push(`  Readability:   ${analysis.breakdown.readability}/15`);
+  lines.push('');
+
+  // Issues
+  if (analysis.issues.length > 0) {
+    lines.push('⚠️ ISSUES');
+    lines.push('─'.repeat(60));
+    for (const issue of analysis.issues) {
+      lines.push(`  • ${issue}`);
+    }
+    lines.push('');
+  }
+
+  // Suggestions
+  if (analysis.suggestions.length > 0) {
+    lines.push('💡 SUGGESTIONS');
+    lines.push('─'.repeat(60));
+    for (const suggestion of analysis.suggestions) {
+      lines.push(`  • ${suggestion}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('═'.repeat(60));
+
+  return lines.join('\n');
+}

package/src/content/index.ts

@@ -0,0 +1,62 @@
+// Content Analysis & Optimization Module
+// Tools for analyzing and optimizing content for SEO
+
+// Readability Analysis
+export {
+  analyzeReadability,
+  formatReadabilityReport,
+  type ReadabilityResult,
+} from './readability.js';
+
+// Search Intent Classification
+export {
+  classifyIntent,
+  classifyIntents,
+  formatIntentReport,
+  type SearchIntent,
+  type IntentAnalysis,
+} from './intent.js';
+
+// Headline Analysis
+export {
+  analyzeHeadline,
+  generateHeadlineVariations,
+  formatHeadlineReport,
+  type HeadlineAnalysis,
+} from './headline.js';
+
+// Featured Snippet Optimization
+export {
+  analyzeFeaturedSnippetPotential,
+  formatFeaturedSnippetReport,
+  type SnippetType,
+  type FeaturedSnippetAnalysis,
+  type SnippetRecommendation,
+} from './featured-snippet.js';
+
+// Keyword Density & LSI
+export {
+  analyzeKeywordDensity,
+  findLSIKeywords,
+  calculateTFIDF,
+  formatKeywordDensityReport,
+  type KeywordDensityAnalysis,
+  type LSIKeyword,
+  type ContentElements,
+} from './keyword-density.js';
+
+// Content Generation
+export {
+  generateBlogPost,
+  generateChangelog,
+  optimizeReadme,
+  scoreContentSEO,
+  type BlogPostConfig,
+  type ChangelogConfig,
+  type ReadmeConfig,
+  type GeneratedContent,
+  type ChangelogResult,
+  type ReadmeResult,
+  type SEOScore,
+  type ContentGeneratorOptions,
+} from './generator.js';

package/src/content/intent.ts

@@ -0,0 +1,258 @@
+// Search Intent Classification
+// Categorizes queries as informational, navigational, transactional, or commercial
+
+export type SearchIntent = 'informational' | 'navigational' | 'transactional' | 'commercial';
+
+export interface IntentAnalysis {
+  intent: SearchIntent;
+  confidence: number; // 0-100
+  signals: string[];
+  recommendedContentFormat: string;
+  contentSuggestions: string[];
+}
+
+/**
+ * Classify search intent for a keyword/query
+ */
+export function classifyIntent(query: string): IntentAnalysis {
+  const q = query.toLowerCase().trim();
+  const signals: string[] = [];
+  const scores: Record<SearchIntent, number> = {
+    informational: 0,
+    navigational: 0,
+    transactional: 0,
+    commercial: 0,
+  };
+
+  // Informational signals (user wants to learn)
+  const informationalPatterns = [
+    { pattern: /^(what|who|why|when|where|which)\b/, weight: 30, signal: 'Question word (what/who/why)' },
+    { pattern: /^how (to|do|does|can|should)\b/, weight: 35, signal: 'How-to question' },
+    { pattern: /\b(guide|tutorial|learn|understand|explain)\b/, weight: 25, signal: 'Learning intent' },
+    { pattern: /\b(definition|meaning|example|history)\b/, weight: 25, signal: 'Definition/meaning query' },
+    { pattern: /\b(tips|ideas|ways to|steps)\b/, weight: 20, signal: 'Tips/ideas request' },
+    { pattern: /^(is|are|can|does|do)\b/, weight: 15, signal: 'Yes/no question' },
+    { pattern: /\b(vs|versus|difference between|compared to)\b/, weight: 20, signal: 'Comparison query' },
+  ];
+
+  // Navigational signals (user wants to go somewhere specific)
+  const navigationalPatterns = [
+    { pattern: /\b(login|sign in|log in|signin)\b/, weight: 40, signal: 'Login intent' },
+    { pattern: /\b(\.com|\.org|\.net|\.io)\b/, weight: 35, signal: 'Domain in query' },
+    { pattern: /\b(official|website|homepage|site)\b/, weight: 30, signal: 'Website reference' },
+    { pattern: /\b(facebook|twitter|instagram|youtube|linkedin|github)\b/, weight: 40, signal: 'Social platform' },
+    { pattern: /\b(amazon|google|apple|microsoft)\b/, weight: 25, signal: 'Brand name' },
+    { pattern: /\b(app|download|install)\b/, weight: 20, signal: 'App/download intent' },
+  ];
+
+  // Transactional signals (user wants to take action/buy)
+  const transactionalPatterns = [
+    { pattern: /\b(buy|purchase|order|shop)\b/, weight: 40, signal: 'Purchase intent' },
+    { pattern: /\b(price|pricing|cost|cheap|discount|deal|sale|coupon)\b/, weight: 35, signal: 'Price interest' },
+    { pattern: /\b(free trial|free download|download free)\b/, weight: 30, signal: 'Free trial/download' },
+    { pattern: /\b(subscribe|sign up|signup|register)\b/, weight: 30, signal: 'Signup intent' },
+    { pattern: /\b(book|reserve|schedule|appointment)\b/, weight: 30, signal: 'Booking intent' },
+    { pattern: /\b(hire|service|quote)\b/, weight: 25, signal: 'Service request' },
+    { pattern: /\b(near me|nearby|local)\b/, weight: 25, signal: 'Local intent' },
+  ];
+
+  // Commercial investigation signals (user researching before purchase)
+  const commercialPatterns = [
+    { pattern: /\b(best|top|review|reviews)\b/, weight: 35, signal: 'Review/best-of query' },
+    { pattern: /\b(comparison|compare|vs|versus|or)\b/, weight: 30, signal: 'Comparison shopping' },
+    { pattern: /\b(alternative|alternatives to)\b/, weight: 30, signal: 'Alternative search' },
+    { pattern: /\b(pros and cons|advantages|disadvantages)\b/, weight: 25, signal: 'Evaluation query' },
+    { pattern: /\b(worth it|should i|is it good)\b/, weight: 25, signal: 'Purchase consideration' },
+    { pattern: /\b(for (small business|enterprise|startups|developers))\b/, weight: 20, signal: 'Segment-specific' },
+    { pattern: /\b20\d{2}\b/, weight: 15, signal: 'Year reference (recency)' },
+  ];
+
+  // Calculate scores
+  for (const p of informationalPatterns) {
+    if (p.pattern.test(q)) {
+      scores.informational += p.weight;
+      signals.push(`[INFO] ${p.signal}`);
+    }
+  }
+
+  for (const p of navigationalPatterns) {
+    if (p.pattern.test(q)) {
+      scores.navigational += p.weight;
+      signals.push(`[NAV] ${p.signal}`);
+    }
+  }
+
+  for (const p of transactionalPatterns) {
+    if (p.pattern.test(q)) {
+      scores.transactional += p.weight;
+      signals.push(`[TRANS] ${p.signal}`);
+    }
+  }
+
+  for (const p of commercialPatterns) {
+    if (p.pattern.test(q)) {
+      scores.commercial += p.weight;
+      signals.push(`[COMM] ${p.signal}`);
+    }
+  }
+
+  // Determine winner
+  const maxScore = Math.max(...Object.values(scores));
+  let intent: SearchIntent = 'informational'; // Default
+
+  if (maxScore === 0) {
+    // No clear signals, use heuristics
+    const wordCount = q.split(/\s+/).length;
+    if (wordCount <= 2) {
+      intent = 'navigational';
+      signals.push('[DEFAULT] Short query - likely navigational');
+    } else {
+      intent = 'informational';
+      signals.push('[DEFAULT] No clear signals - defaulting to informational');
+    }
+  } else {
+    intent = (Object.entries(scores) as [SearchIntent, number][])
+      .sort((a, b) => b[1] - a[1])[0][0];
+  }
+
+  // Calculate confidence
+  const totalScore = Object.values(scores).reduce((a, b) => a + b, 0);
+  const confidence = totalScore > 0
+    ? Math.min(100, Math.round((scores[intent] / totalScore) * 100))
+    : 50;
+
+  // Get recommendations
+  const { recommendedContentFormat, contentSuggestions } = getContentRecommendations(intent);
+
+  return {
+    intent,
+    confidence,
+    signals,
+    recommendedContentFormat,
+    contentSuggestions,
+  };
+}
+
+function getContentRecommendations(intent: SearchIntent): {
+  recommendedContentFormat: string;
+  contentSuggestions: string[];
+} {
+  switch (intent) {
+    case 'informational':
+      return {
+        recommendedContentFormat: 'Long-form blog post, guide, or tutorial',
+        contentSuggestions: [
+          'Create comprehensive how-to content',
+          'Include step-by-step instructions',
+          'Add FAQ section for related questions',
+          'Use clear headings (H2, H3) for scanability',
+          'Include images/diagrams to illustrate concepts',
+          'Target featured snippet with direct answers',
+        ],
+      };
+
+    case 'navigational':
+      return {
+        recommendedContentFormat: 'Brand landing page or homepage',
+        contentSuggestions: [
+          'Ensure brand name is in title and H1',
+          'Include clear navigation to key sections',
+          'Add structured data for organization/website',
+          'Optimize for brand + product variations',
+          'Include social proof and trust signals',
+        ],
+      };
+
+    case 'transactional':
+      return {
+        recommendedContentFormat: 'Product page or service landing page',
+        contentSuggestions: [
+          'Include clear CTA (Buy, Sign Up, Download)',
+          'Show pricing information prominently',
+          'Add product schema markup',
+          'Include trust signals (reviews, testimonials)',
+          'Optimize for "buy", "price", "discount" variations',
+          'Add urgency elements (limited time, stock)',
+        ],
+      };
+
+    case 'commercial':
+      return {
+        recommendedContentFormat: 'Comparison page, review, or buying guide',
+        contentSuggestions: [
+          'Create detailed comparison tables',
+          'Include pros and cons lists',
+          'Add expert opinions or user reviews',
+          'Compare features, pricing, use cases',
+          'Include clear recommendation/winner',
+          'Add affiliate-friendly product links',
+        ],
+      };
+  }
+}
+
+/**
+ * Batch classify multiple keywords
+ */
+export function classifyIntents(keywords: string[]): Map<string, IntentAnalysis> {
+  const results = new Map<string, IntentAnalysis>();
+  for (const kw of keywords) {
+    results.set(kw, classifyIntent(kw));
+  }
+  return results;
+}
+
+/**
+ * Format intent analysis report
+ */
+export function formatIntentReport(query: string, analysis: IntentAnalysis): string {
+  const lines: string[] = [];
+
+  const intentIcons: Record<SearchIntent, string> = {
+    informational: '📚',
+    navigational: '🧭',
+    transactional: '💰',
+    commercial: '🔍',
+  };
+
+  lines.push('');
+  lines.push('═'.repeat(60));
+  lines.push('  SEARCH INTENT ANALYSIS');
+  lines.push('═'.repeat(60));
+  lines.push('');
+
+  lines.push(`Query: "${query}"`);
+  lines.push('');
+
+  lines.push(`${intentIcons[analysis.intent]} Intent: ${analysis.intent.toUpperCase()}`);
+  lines.push(`   Confidence: ${analysis.confidence}%`);
+  lines.push('');
+
+  // Signals
+  if (analysis.signals.length > 0) {
+    lines.push('📊 SIGNALS DETECTED');
+    lines.push('─'.repeat(60));
+    for (const signal of analysis.signals) {
+      lines.push(`  • ${signal}`);
+    }
+    lines.push('');
+  }
+
+  // Content format
+  lines.push('📝 RECOMMENDED CONTENT');
+  lines.push('─'.repeat(60));
+  lines.push(`  Format: ${analysis.recommendedContentFormat}`);
+  lines.push('');
+
+  // Suggestions
+  lines.push('💡 CONTENT SUGGESTIONS');
+  lines.push('─'.repeat(60));
+  for (const suggestion of analysis.contentSuggestions) {
+    lines.push(`  • ${suggestion}`);
+  }
+  lines.push('');
+
+  lines.push('═'.repeat(60));
+
+  return lines.join('\n');
+}