@rankcli/agent-runtime 0.0.15 → 0.0.16

package/src/keywords/topic-grouping.ts

@@ -1,327 +0,0 @@
-// Keyword Topic Grouping/Clustering
-// Groups keywords by parent topic for content planning
-
-import type { KeywordData } from './types.js';
-
-export interface KeywordTopic {
-  topic: string;
-  keywords: KeywordData[];
-  totalVolume: number;
-  avgDifficulty: number;
-  contentType: 'hub' | 'pillar' | 'cluster';
-}
-
-export interface TopicClusterResult {
-  topics: KeywordTopic[];
-  uncategorized: KeywordData[];
-  contentStrategy: ContentRecommendation[];
-}
-
-export interface ContentRecommendation {
-  topic: string;
-  pageType: 'pillar-page' | 'blog-post' | 'faq-page' | 'landing-page';
-  targetKeywords: string[];
-  potentialTraffic: number;
-  difficulty: 'easy' | 'medium' | 'hard';
-}
-
-/**
- * Group keywords into topic clusters using multiple strategies:
- * 1. Shared root words
- * 2. Semantic similarity (common terms)
- * 3. Intent matching (questions, how-to, etc.)
- * 4. N-gram overlap
- */
-export function groupKeywordsByTopic(keywords: KeywordData[]): TopicClusterResult {
-  const topicMap = new Map<string, KeywordData[]>();
-  const uncategorized: KeywordData[] = [];
-
-  // Step 1: Extract potential topics from keywords
-  const topicCandidates = extractTopicCandidates(keywords);
-
-  // Step 2: Assign keywords to topics
-  for (const kw of keywords) {
-    const matchedTopic = findBestTopic(kw.keyword, topicCandidates);
-
-    if (matchedTopic) {
-      if (!topicMap.has(matchedTopic)) {
-        topicMap.set(matchedTopic, []);
-      }
-      topicMap.get(matchedTopic)!.push(kw);
-    } else {
-      uncategorized.push(kw);
-    }
-  }
-
-  // Step 3: Create topic objects with metrics
-  const topics: KeywordTopic[] = [];
-
-  for (const [topic, kwList] of topicMap) {
-    if (kwList.length < 2) {
-      // Move single-keyword topics to uncategorized
-      uncategorized.push(...kwList);
-      continue;
-    }
-
-    const totalVolume = kwList.reduce((sum, k) => sum + k.searchVolume, 0);
-    const avgDifficulty = Math.round(
-      kwList.reduce((sum, k) => sum + k.keywordDifficulty, 0) / kwList.length
-    );
-
-    // Determine content type based on cluster size and volume
-    let contentType: 'hub' | 'pillar' | 'cluster';
-    if (kwList.length >= 10 || totalVolume >= 5000) {
-      contentType = 'hub';
-    } else if (kwList.length >= 5 || totalVolume >= 1000) {
-      contentType = 'pillar';
-    } else {
-      contentType = 'cluster';
-    }
-
-    topics.push({
-      topic,
-      keywords: kwList.sort((a, b) => b.searchVolume - a.searchVolume),
-      totalVolume,
-      avgDifficulty,
-      contentType,
-    });
-  }
-
-  // Sort topics by total volume
-  topics.sort((a, b) => b.totalVolume - a.totalVolume);
-
-  // Step 4: Generate content strategy recommendations
-  const contentStrategy = generateContentStrategy(topics);
-
-  return { topics, uncategorized, contentStrategy };
-}
-
-function extractTopicCandidates(keywords: KeywordData[]): Map<string, number> {
-  const wordFrequency = new Map<string, number>();
-  const bigramFrequency = new Map<string, number>();
-
-  // Count word and bigram frequencies
-  for (const kw of keywords) {
-    const words = kw.keyword.toLowerCase()
-      .replace(/[^\w\s]/g, '')
-      .split(/\s+/)
-      .filter(w => w.length > 2 && !isStopWord(w));
-
-    // Single words
-    for (const word of words) {
-      wordFrequency.set(word, (wordFrequency.get(word) || 0) + 1);
-    }
-
-    // Bigrams (2-word phrases)
-    for (let i = 0; i < words.length - 1; i++) {
-      const bigram = `${words[i]} ${words[i + 1]}`;
-      bigramFrequency.set(bigram, (bigramFrequency.get(bigram) || 0) + 1);
-    }
-  }
-
-  // Combine and filter - prefer bigrams that appear frequently
-  const candidates = new Map<string, number>();
-
-  // Add frequent bigrams first (they make better topics)
-  for (const [bigram, count] of bigramFrequency) {
-    if (count >= 2) {
-      candidates.set(bigram, count * 2); // Weight bigrams higher
-    }
-  }
-
-  // Add frequent single words
-  for (const [word, count] of wordFrequency) {
-    if (count >= 3 && !candidates.has(word)) {
-      candidates.set(word, count);
-    }
-  }
-
-  return candidates;
-}
-
-function findBestTopic(keyword: string, topicCandidates: Map<string, number>): string | null {
-  const kwLower = keyword.toLowerCase();
-  let bestTopic: string | null = null;
-  let bestScore = 0;
-
-  for (const [topic, frequency] of topicCandidates) {
-    if (kwLower.includes(topic)) {
-      // Score based on how much of the keyword this topic covers
-      const coverage = topic.length / kwLower.length;
-      const score = frequency * coverage;
-
-      if (score > bestScore) {
-        bestScore = score;
-        bestTopic = topic;
-      }
-    }
-  }
-
-  // Also check for intent-based grouping
-  if (!bestTopic) {
-    const intent = classifyIntent(keyword);
-    if (intent !== 'other') {
-      // Group questions together, how-tos together, etc.
-      const intentTopics: Record<string, string> = {
-        question: 'FAQ / Questions',
-        'how-to': 'How-To Guides',
-        comparison: 'Comparisons',
-        best: 'Best / Top Lists',
-        review: 'Reviews',
-      };
-      if (intentTopics[intent]) {
-        return intentTopics[intent];
-      }
-    }
-  }
-
-  return bestTopic;
-}
-
-function classifyIntent(keyword: string): string {
-  const kw = keyword.toLowerCase();
-
-  if (/^(what|why|when|where|who|which|how|can|is|are|does|do)\b/.test(kw)) {
-    return 'question';
-  }
-  if (kw.startsWith('how to ')) {
-    return 'how-to';
-  }
-  if (/\b(vs|versus|compared|comparison|alternative)\b/.test(kw)) {
-    return 'comparison';
-  }
-  if (/^(best|top|greatest)\b/.test(kw)) {
-    return 'best';
-  }
-  if (/\b(review|reviews)\b/.test(kw)) {
-    return 'review';
-  }
-
-  return 'other';
-}
-
-function isStopWord(word: string): boolean {
-  const stopWords = new Set([
-    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
-    'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'were', 'been',
-    'be', 'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would',
-    'could', 'should', 'may', 'might', 'must', 'shall', 'can', 'need',
-    'it', 'its', 'this', 'that', 'these', 'those', 'i', 'you', 'he', 'she',
-    'we', 'they', 'what', 'which', 'who', 'when', 'where', 'why', 'how',
-    'all', 'each', 'every', 'both', 'few', 'more', 'most', 'other', 'some',
-    'such', 'no', 'not', 'only', 'own', 'same', 'so', 'than', 'too', 'very',
-    'just', 'also', 'now', 'new', 'first', 'last', 'long', 'great', 'little',
-    'own', 'other', 'old', 'right', 'big', 'high', 'different', 'small',
-    'large', 'next', 'early', 'young', 'important', 'public', 'bad', 'same',
-  ]);
-  return stopWords.has(word);
-}
-
-function generateContentStrategy(topics: KeywordTopic[]): ContentRecommendation[] {
-  const recommendations: ContentRecommendation[] = [];
-
-  for (const topic of topics.slice(0, 10)) {
-    // Determine page type based on topic characteristics
-    let pageType: ContentRecommendation['pageType'];
-    let targetKeywords: string[] = [];
-
-    if (topic.topic === 'FAQ / Questions') {
-      pageType = 'faq-page';
-      targetKeywords = topic.keywords.slice(0, 10).map(k => k.keyword);
-    } else if (topic.topic === 'How-To Guides') {
-      pageType = 'blog-post';
-      targetKeywords = topic.keywords.slice(0, 5).map(k => k.keyword);
-    } else if (topic.contentType === 'hub') {
-      pageType = 'pillar-page';
-      targetKeywords = topic.keywords.slice(0, 8).map(k => k.keyword);
-    } else if (topic.avgDifficulty < 20) {
-      pageType = 'blog-post';
-      targetKeywords = topic.keywords.slice(0, 5).map(k => k.keyword);
-    } else {
-      pageType = 'landing-page';
-      targetKeywords = topic.keywords.slice(0, 3).map(k => k.keyword);
-    }
-
-    // Determine difficulty
-    let difficulty: ContentRecommendation['difficulty'];
-    if (topic.avgDifficulty < 20) {
-      difficulty = 'easy';
-    } else if (topic.avgDifficulty < 40) {
-      difficulty = 'medium';
-    } else {
-      difficulty = 'hard';
-    }
-
-    recommendations.push({
-      topic: topic.topic,
-      pageType,
-      targetKeywords,
-      potentialTraffic: topic.totalVolume,
-      difficulty,
-    });
-  }
-
-  return recommendations;
-}
-
-/**
- * Format topic grouping report
- */
-export function formatTopicReport(result: TopicClusterResult): string {
-  const lines: string[] = [];
-
-  lines.push('');
-  lines.push('═'.repeat(70));
-  lines.push('  KEYWORD TOPIC CLUSTERS');
-  lines.push('═'.repeat(70));
-  lines.push('');
-
-  for (const topic of result.topics.slice(0, 8)) {
-    const icon = topic.contentType === 'hub' ? '📚' :
-                 topic.contentType === 'pillar' ? '📄' : '📝';
-
-    lines.push(`${icon} TOPIC: ${topic.topic.toUpperCase()}`);
-    lines.push('─'.repeat(70));
-    lines.push(`  Type: ${topic.contentType.toUpperCase()} | Keywords: ${topic.keywords.length} | Volume: ${topic.totalVolume} | Avg KD: ${topic.avgDifficulty}`);
-    lines.push('');
-    lines.push('  Top Keywords:');
-
-    for (const kw of topic.keywords.slice(0, 5)) {
-      const vol = String(kw.searchVolume).padStart(6);
-      const kd = String(kw.keywordDifficulty).padStart(3);
-      lines.push(`    • ${kw.keyword.substring(0, 40).padEnd(42)} Vol: ${vol}  KD: ${kd}`);
-    }
-
-    if (topic.keywords.length > 5) {
-      lines.push(`    ... and ${topic.keywords.length - 5} more keywords`);
-    }
-    lines.push('');
-  }
-
-  // Content strategy recommendations
-  if (result.contentStrategy.length > 0) {
-    lines.push('📋 CONTENT STRATEGY RECOMMENDATIONS');
-    lines.push('─'.repeat(70));
-    lines.push('');
-
-    for (const rec of result.contentStrategy.slice(0, 5)) {
-      const diffIcon = rec.difficulty === 'easy' ? '🟢' :
-                       rec.difficulty === 'medium' ? '🟡' : '🔴';
-
-      lines.push(`  ${diffIcon} Create a ${rec.pageType.replace('-', ' ').toUpperCase()} for "${rec.topic}"`);
-      lines.push(`     Potential traffic: ~${rec.potentialTraffic}/month`);
-      lines.push(`     Target keywords: ${rec.targetKeywords.slice(0, 3).join(', ')}`);
-      lines.push('');
-    }
-  }
-
-  // Uncategorized
-  if (result.uncategorized.length > 0) {
-    lines.push(`📌 ${result.uncategorized.length} keywords didn't fit into topic clusters`);
-    lines.push('');
-  }
-
-  lines.push('═'.repeat(70));
-
-  return lines.join('\n');
-}

package/src/keywords/types.ts

@@ -1,144 +0,0 @@
-// Keyword Research Types
-
-export interface SiteProfile {
-  domain: string;
-  domainAge: 'new' | 'established' | 'authority';
-  backlinkCount: 'none' | 'few' | 'some' | 'many';
-  businessGoal: 'signups' | 'purchases' | 'leads' | 'awareness';
-  contentCapacity: 'low' | 'medium' | 'high';
-  targetGeo: string;
-}
-
-export interface KeywordData {
-  keyword: string;
-  searchVolume: number;
-  keywordDifficulty: number;
-  cpc?: number;
-  trafficPotential?: number;
-  intent?: 'informational' | 'commercial' | 'transactional' | 'navigational';
-  trend?: 'up' | 'down' | 'stable';
-  source: 'gsc' | 'dataforseo' | 'autocomplete' | 'manual' | 'competitor';
-}
-
-export interface KeywordOpportunity extends KeywordData {
-  priorityScore: number;
-  category: 'quick-win' | 'medium-term' | 'long-term';
-  suggestedAction: KeywordAction;
-  currentRanking?: number;
-  impressions?: number;
-  clicks?: number;
-  ctr?: number;
-}
-
-export interface KeywordAction {
-  type: 'add-to-title' | 'add-to-h1' | 'add-to-meta' | 'create-content' | 'optimize-existing';
-  description: string;
-  targetElement?: string;
-  currentValue?: string;
-  suggestedValue?: string;
-  file?: string;
-  line?: number;
-}
-
-export interface KeywordResearchResult {
-  siteProfile: SiteProfile;
-  keywords: KeywordOpportunity[];
-  quickWins: KeywordOpportunity[];
-  mediumTerm: KeywordOpportunity[];
-  longTerm: KeywordOpportunity[];
-  recommendations: string[];
-  maxKdThreshold: number;
-}
-
-export interface GSCQueryData {
-  query: string;
-  clicks: number;
-  impressions: number;
-  ctr: number;
-  position: number;
-}
-
-// Questions to ask the user
-export const SITE_PROFILE_QUESTIONS = [
-  {
-    id: 'domainAge',
-    question: 'How old is your domain?',
-    options: [
-      { value: 'new', label: 'New (< 6 months)', description: 'Just started, building from scratch' },
-      { value: 'established', label: 'Established (6 months - 2 years)', description: 'Has some history and content' },
-      { value: 'authority', label: 'Authority (2+ years)', description: 'Well-established with backlinks' },
-    ],
-    impact: 'Determines the maximum keyword difficulty you should target',
-  },
-  {
-    id: 'backlinkCount',
-    question: 'How many backlinks does your site have?',
-    options: [
-      { value: 'none', label: 'None or very few (0-10)', description: 'Just starting link building' },
-      { value: 'few', label: 'Some (10-50)', description: 'A few quality backlinks' },
-      { value: 'some', label: 'Moderate (50-200)', description: 'Decent backlink profile' },
-      { value: 'many', label: 'Many (200+)', description: 'Strong backlink profile' },
-    ],
-    impact: 'Affects your ability to rank for competitive keywords',
-  },
-  {
-    id: 'businessGoal',
-    question: 'What is your primary business goal?',
-    options: [
-      { value: 'signups', label: 'Get signups/registrations', description: 'SaaS, apps, newsletters' },
-      { value: 'purchases', label: 'Generate purchases', description: 'E-commerce, products' },
-      { value: 'leads', label: 'Capture leads', description: 'B2B, services, consulting' },
-      { value: 'awareness', label: 'Build brand awareness', description: 'Content, community, thought leadership' },
-    ],
-    impact: 'Weights commercial vs informational keywords',
-  },
-  {
-    id: 'contentCapacity',
-    question: 'How much content can you produce monthly?',
-    options: [
-      { value: 'low', label: '1-2 pages/month', description: 'Limited time or resources' },
-      { value: 'medium', label: '3-5 pages/month', description: 'Moderate content output' },
-      { value: 'high', label: '5+ pages/month', description: 'Dedicated content team' },
-    ],
-    impact: 'Determines how many keywords to suggest',
-  },
-  {
-    id: 'targetGeo',
-    question: 'Where are your target customers?',
-    options: [
-      { value: 'us', label: 'United States', description: 'Primary US audience' },
-      { value: 'uk', label: 'United Kingdom', description: 'Primary UK audience' },
-      { value: 'global', label: 'Global', description: 'Worldwide audience' },
-      { value: 'other', label: 'Other', description: 'Specific country or region' },
-    ],
-    impact: 'Determines which search volume data to use',
-  },
-] as const;
-
-// KD thresholds based on site profile
-export function getMaxKdThreshold(profile: SiteProfile): number {
-  const ageMultiplier = {
-    new: 1,
-    established: 2,
-    authority: 3,
-  };
-
-  const backlinkMultiplier = {
-    none: 1,
-    few: 1.2,
-    some: 1.5,
-    many: 2,
-  };
-
-  const baseKd = 10;
-  const maxKd = baseKd * ageMultiplier[profile.domainAge] * backlinkMultiplier[profile.backlinkCount];
-
-  return Math.min(Math.round(maxKd), 50); // Cap at 50
-}
-
-// Priority weights
-export const PRIORITY_WEIGHTS = {
-  businessValue: 0.40,
-  difficulty: 0.35,
-  trafficPotential: 0.25,
-};