@rankcli/agent-runtime 0.0.15 → 0.0.17

package/src/content/headline.ts

@@ -1,317 +0,0 @@
-// 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

@@ -1,62 +0,0 @@
-// 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

@@ -1,258 +0,0 @@
-// 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');
-}