myaidev-method 0.2.23 → 0.2.24-1

package/src/lib/seo-optimizer.js

@@ -0,0 +1,515 @@
+/**
+ * SEO Optimizer
+ * SEO optimization utilities for content generation
+ * Provides analysis, recommendations, and optimization functions
+ */
+
+// SEO configuration defaults
+const SEO_DEFAULTS = {
+  titleMinLength: 30,
+  titleMaxLength: 60,
+  descriptionMinLength: 120,
+  descriptionMaxLength: 160,
+  minKeywordDensity: 0.5,
+  maxKeywordDensity: 2.5,
+  minWordCount: 300,
+  idealWordCount: 1500,
+  maxWordCount: 5000,
+  minHeadings: 2,
+  minParagraphs: 3,
+  maxParagraphLength: 300,
+  idealSentenceLength: 20
+};
+
+/**
+ * SEO Optimizer Class
+ */
+export class SEOOptimizer {
+  constructor(options = {}) {
+    this.config = { ...SEO_DEFAULTS, ...options };
+  }
+
+  /**
+   * Optimize content for SEO
+   * @param {string} content - Content to optimize
+   * @param {string[]} keywords - Target keywords
+   * @param {string} title - Content title
+   * @returns {Object} Optimization result with content and analysis
+   */
+  optimizeContent(content, keywords = [], title = '') {
+    let optimized = content;
+
+    // Ensure proper heading structure
+    optimized = this.optimizeHeadings(optimized, keywords);
+
+    // Optimize paragraph structure
+    optimized = this.optimizeParagraphs(optimized);
+
+    // Add keyword variations if density is too low
+    if (keywords.length > 0) {
+      const analysis = this.analyzeKeywordDensity(optimized, keywords);
+      if (analysis.overallDensity < this.config.minKeywordDensity) {
+        optimized = this.enhanceKeywordPresence(optimized, keywords);
+      }
+    }
+
+    // Analyze the optimized content
+    const seoAnalysis = this.analyzeSEO(optimized, keywords, title);
+
+    return {
+      content: optimized,
+      analysis: seoAnalysis,
+      optimized: true
+    };
+  }
+
+  /**
+   * Generate meta description from content
+   * @param {string} content - Content to summarize
+   * @param {number} [maxLength=160] - Maximum description length
+   * @returns {string} Meta description
+   */
+  generateMetaDescription(content, maxLength = this.config.descriptionMaxLength) {
+    // Remove markdown formatting
+    let text = content
+      .replace(/^#{1,6}\s+.+$/gm, '') // Remove headings
+      .replace(/\*\*(.+?)\*\*/g, '$1') // Remove bold
+      .replace(/\*(.+?)\*/g, '$1') // Remove italic
+      .replace(/\[(.+?)\]\(.+?\)/g, '$1') // Remove links
+      .replace(/`(.+?)`/g, '$1') // Remove code
+      .replace(/\n+/g, ' ') // Replace newlines with spaces
+      .trim();
+
+    // Get the first paragraph or substantial text
+    const sentences = text.split(/[.!?]+/).filter(s => s.trim().length > 0);
+    let description = '';
+
+    for (const sentence of sentences) {
+      const trimmed = sentence.trim();
+      if (description.length + trimmed.length + 2 <= maxLength) {
+        description += (description ? '. ' : '') + trimmed;
+      } else {
+        break;
+      }
+    }
+
+    // Ensure we have a complete thought
+    if (description.length < this.config.descriptionMinLength && sentences.length > 0) {
+      description = sentences[0].trim();
+      if (description.length > maxLength) {
+        description = description.substring(0, maxLength - 3) + '...';
+      }
+    }
+
+    // Add period if missing
+    if (description && !description.match(/[.!?]$/)) {
+      description += '.';
+    }
+
+    return description;
+  }
+
+  /**
+   * Generate URL-friendly slug from title
+   * @param {string} title - Title to slugify
+   * @returns {string} URL-safe slug
+   */
+  generateSlug(title) {
+    return title
+      .toLowerCase()
+      .trim()
+      // Remove special characters except spaces and hyphens
+      .replace(/[^\w\s-]/g, '')
+      // Replace spaces and underscores with hyphens
+      .replace(/[\s_]+/g, '-')
+      // Remove multiple consecutive hyphens
+      .replace(/-+/g, '-')
+      // Remove leading/trailing hyphens
+      .replace(/^-+|-+$/g, '');
+  }
+
+  /**
+   * Analyze SEO metrics for content
+   * @param {string} content - Content to analyze
+   * @param {string[]} keywords - Target keywords
+   * @param {string} [title=''] - Content title
+   * @returns {Object} SEO analysis result
+   */
+  analyzeSEO(content, keywords = [], title = '') {
+    const issues = [];
+    const recommendations = [];
+    let score = 100;
+
+    // Word count analysis
+    const wordCount = this.getWordCount(content);
+    if (wordCount < this.config.minWordCount) {
+      issues.push(`Content is too short (${wordCount} words). Minimum recommended: ${this.config.minWordCount}`);
+      score -= 15;
+    } else if (wordCount < this.config.idealWordCount) {
+      recommendations.push(`Consider expanding content to ${this.config.idealWordCount}+ words for better SEO`);
+      score -= 5;
+    } else if (wordCount > this.config.maxWordCount) {
+      recommendations.push('Content is quite long. Consider splitting into multiple articles');
+    }
+
+    // Title analysis
+    if (title) {
+      const titleAnalysis = this.analyzeTitle(title, keywords);
+      issues.push(...titleAnalysis.issues);
+      recommendations.push(...titleAnalysis.recommendations);
+      score -= titleAnalysis.issues.length * 10;
+    }
+
+    // Heading analysis
+    const headingAnalysis = this.analyzeHeadings(content, keywords);
+    issues.push(...headingAnalysis.issues);
+    recommendations.push(...headingAnalysis.recommendations);
+    score -= headingAnalysis.issues.length * 5;
+
+    // Keyword analysis
+    if (keywords.length > 0) {
+      const keywordAnalysis = this.analyzeKeywordDensity(content, keywords);
+      issues.push(...keywordAnalysis.issues);
+      recommendations.push(...keywordAnalysis.recommendations);
+      score -= keywordAnalysis.issues.length * 8;
+    }
+
+    // Readability analysis
+    const readabilityAnalysis = this.analyzeReadability(content);
+    issues.push(...readabilityAnalysis.issues);
+    recommendations.push(...readabilityAnalysis.recommendations);
+    score -= readabilityAnalysis.issues.length * 3;
+
+    // Structure analysis
+    const structureAnalysis = this.analyzeStructure(content);
+    issues.push(...structureAnalysis.issues);
+    recommendations.push(...structureAnalysis.recommendations);
+    score -= structureAnalysis.issues.length * 5;
+
+    // Ensure score is within bounds
+    score = Math.max(0, Math.min(100, score));
+
+    return {
+      score,
+      wordCount,
+      issues,
+      recommendations,
+      grade: this.getGrade(score),
+      keywordDensity: keywords.length > 0 ? this.analyzeKeywordDensity(content, keywords).overallDensity : null
+    };
+  }
+
+  /**
+   * Analyze title for SEO
+   * @param {string} title - Title to analyze
+   * @param {string[]} keywords - Target keywords
+   * @returns {Object} Title analysis
+   */
+  analyzeTitle(title, keywords = []) {
+    const issues = [];
+    const recommendations = [];
+
+    // Length check
+    if (title.length < this.config.titleMinLength) {
+      issues.push(`Title is too short (${title.length} chars). Minimum: ${this.config.titleMinLength}`);
+    } else if (title.length > this.config.titleMaxLength) {
+      issues.push(`Title is too long (${title.length} chars). Maximum: ${this.config.titleMaxLength}`);
+    }
+
+    // Keyword presence
+    if (keywords.length > 0) {
+      const titleLower = title.toLowerCase();
+      const primaryKeyword = keywords[0].toLowerCase();
+
+      if (!titleLower.includes(primaryKeyword)) {
+        recommendations.push(`Consider including primary keyword "${keywords[0]}" in the title`);
+      }
+
+      // Check if keyword is near the beginning
+      const keywordIndex = titleLower.indexOf(primaryKeyword);
+      if (keywordIndex > 20) {
+        recommendations.push('Move primary keyword closer to the beginning of the title');
+      }
+    }
+
+    // Power words check
+    const powerWords = ['ultimate', 'complete', 'essential', 'proven', 'best', 'top', 'guide', 'how to'];
+    const hassPowerWord = powerWords.some(word => title.toLowerCase().includes(word));
+    if (!hassPowerWord) {
+      recommendations.push('Consider adding a power word to make the title more compelling');
+    }
+
+    return { issues, recommendations };
+  }
+
+  /**
+   * Analyze headings structure
+   * @param {string} content - Content to analyze
+   * @param {string[]} keywords - Target keywords
+   * @returns {Object} Heading analysis
+   */
+  analyzeHeadings(content, keywords = []) {
+    const issues = [];
+    const recommendations = [];
+
+    const headings = content.match(/^#{1,6}\s+.+$/gm) || [];
+    const h2Count = (content.match(/^##\s+.+$/gm) || []).length;
+    const h3Count = (content.match(/^###\s+.+$/gm) || []).length;
+
+    // Check heading count
+    if (headings.length < this.config.minHeadings) {
+      issues.push(`Not enough headings (${headings.length}). Add at least ${this.config.minHeadings} headings`);
+    }
+
+    // Check H2 subheadings
+    if (h2Count < 2) {
+      recommendations.push('Add more H2 subheadings to improve content structure');
+    }
+
+    // Check for keyword in headings
+    if (keywords.length > 0) {
+      const keywordsInHeadings = keywords.filter(kw =>
+        headings.some(h => h.toLowerCase().includes(kw.toLowerCase()))
+      );
+
+      if (keywordsInHeadings.length === 0) {
+        recommendations.push('Include at least one keyword in your headings');
+      }
+    }
+
+    // Check heading hierarchy
+    const hasH1 = (content.match(/^#\s+.+$/gm) || []).length > 0;
+    if (hasH1 && h2Count === 0) {
+      recommendations.push('Add H2 subheadings under your main heading');
+    }
+
+    return { issues, recommendations };
+  }
+
+  /**
+   * Analyze keyword density
+   * @param {string} content - Content to analyze
+   * @param {string[]} keywords - Keywords to check
+   * @returns {Object} Keyword density analysis
+   */
+  analyzeKeywordDensity(content, keywords) {
+    const issues = [];
+    const recommendations = [];
+    const wordCount = this.getWordCount(content);
+    const contentLower = content.toLowerCase();
+
+    const densities = {};
+    let totalOccurrences = 0;
+
+    for (const keyword of keywords) {
+      const keywordLower = keyword.toLowerCase();
+      const regex = new RegExp(keywordLower.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+      const matches = content.match(regex) || [];
+      const count = matches.length;
+      const density = (count / wordCount) * 100;
+
+      densities[keyword] = { count, density: density.toFixed(2) };
+      totalOccurrences += count;
+
+      if (density < this.config.minKeywordDensity) {
+        recommendations.push(`Keyword "${keyword}" density is low (${density.toFixed(2)}%). Consider adding more instances`);
+      } else if (density > this.config.maxKeywordDensity) {
+        issues.push(`Keyword "${keyword}" density is too high (${density.toFixed(2)}%). Risk of keyword stuffing`);
+      }
+    }
+
+    const overallDensity = (totalOccurrences / wordCount) * 100;
+
+    // Check first paragraph
+    const firstParagraph = content.split('\n\n')[0] || '';
+    const primaryKeyword = keywords[0]?.toLowerCase();
+    if (primaryKeyword && !firstParagraph.toLowerCase().includes(primaryKeyword)) {
+      recommendations.push('Include primary keyword in the first paragraph');
+    }
+
+    return {
+      densities,
+      overallDensity: parseFloat(overallDensity.toFixed(2)),
+      issues,
+      recommendations
+    };
+  }
+
+  /**
+   * Analyze content readability
+   * @param {string} content - Content to analyze
+   * @returns {Object} Readability analysis
+   */
+  analyzeReadability(content) {
+    const issues = [];
+    const recommendations = [];
+
+    const sentences = content.split(/[.!?]+/).filter(s => s.trim().length > 0);
+    const words = this.getWords(content);
+
+    // Average sentence length
+    const avgSentenceLength = words.length / sentences.length;
+    if (avgSentenceLength > 25) {
+      issues.push(`Average sentence length is too high (${Math.round(avgSentenceLength)} words). Aim for 15-20 words`);
+    } else if (avgSentenceLength < 10) {
+      recommendations.push('Sentences are quite short. Consider adding more complex sentences for variety');
+    }
+
+    // Paragraph length check
+    const paragraphs = content.split(/\n\n+/).filter(p => p.trim().length > 0);
+    const longParagraphs = paragraphs.filter(p => this.getWordCount(p) > this.config.maxParagraphLength);
+    if (longParagraphs.length > 0) {
+      recommendations.push(`${longParagraphs.length} paragraph(s) are too long. Consider breaking them up`);
+    }
+
+    // Passive voice check (simplified)
+    const passivePatterns = /\b(was|were|is|are|been|being)\s+\w+ed\b/gi;
+    const passiveMatches = content.match(passivePatterns) || [];
+    const passivePercentage = (passiveMatches.length / sentences.length) * 100;
+    if (passivePercentage > 20) {
+      recommendations.push(`High passive voice usage (${Math.round(passivePercentage)}%). Consider using more active voice`);
+    }
+
+    return { issues, recommendations };
+  }
+
+  /**
+   * Analyze content structure
+   * @param {string} content - Content to analyze
+   * @returns {Object} Structure analysis
+   */
+  analyzeStructure(content) {
+    const issues = [];
+    const recommendations = [];
+
+    // Check for lists
+    const hasBulletList = /^[-*]\s+.+$/m.test(content);
+    const hasNumberedList = /^\d+\.\s+.+$/m.test(content);
+    if (!hasBulletList && !hasNumberedList) {
+      recommendations.push('Consider adding bullet points or numbered lists for better readability');
+    }
+
+    // Check for links
+    const linkCount = (content.match(/\[.+?\]\(.+?\)/g) || []).length;
+    if (linkCount === 0) {
+      recommendations.push('Consider adding internal or external links');
+    }
+
+    // Check for images (markdown)
+    const imageCount = (content.match(/!\[.+?\]\(.+?\)/g) || []).length;
+    if (imageCount === 0) {
+      recommendations.push('Consider adding images to improve engagement');
+    }
+
+    // Check for call-to-action
+    const ctaPatterns = /\b(subscribe|sign up|download|learn more|get started|contact|buy now)\b/gi;
+    const hasCTA = ctaPatterns.test(content);
+    if (!hasCTA) {
+      recommendations.push('Consider adding a call-to-action');
+    }
+
+    return { issues, recommendations };
+  }
+
+  /**
+   * Optimize heading structure
+   * @param {string} content - Content to optimize
+   * @param {string[]} keywords - Target keywords
+   * @returns {string} Optimized content
+   */
+  optimizeHeadings(content, keywords) {
+    // This is a helper function - actual heading optimization
+    // would typically be done by the content-writer agent
+    return content;
+  }
+
+  /**
+   * Optimize paragraph structure
+   * @param {string} content - Content to optimize
+   * @returns {string} Optimized content
+   */
+  optimizeParagraphs(content) {
+    // Split overly long paragraphs
+    const paragraphs = content.split(/\n\n+/);
+    const optimized = paragraphs.map(p => {
+      const wordCount = this.getWordCount(p);
+      if (wordCount > this.config.maxParagraphLength) {
+        // Try to split at sentence boundaries
+        const sentences = p.split(/([.!?]\s+)/);
+        let current = '';
+        const parts = [];
+
+        for (let i = 0; i < sentences.length; i += 2) {
+          const sentence = sentences[i] + (sentences[i + 1] || '');
+          if (this.getWordCount(current + sentence) > this.config.maxParagraphLength / 2 && current) {
+            parts.push(current.trim());
+            current = sentence;
+          } else {
+            current += sentence;
+          }
+        }
+        if (current.trim()) {
+          parts.push(current.trim());
+        }
+        return parts.join('\n\n');
+      }
+      return p;
+    });
+
+    return optimized.join('\n\n');
+  }
+
+  /**
+   * Enhance keyword presence in content
+   * @param {string} content - Content to enhance
+   * @param {string[]} keywords - Keywords to include
+   * @returns {string} Enhanced content
+   */
+  enhanceKeywordPresence(content, keywords) {
+    // This is a placeholder - actual keyword enhancement
+    // should be done carefully by the content-writer agent
+    // to maintain natural flow
+    return content;
+  }
+
+  /**
+   * Get word count
+   * @param {string} text - Text to count
+   * @returns {number} Word count
+   */
+  getWordCount(text) {
+    return this.getWords(text).length;
+  }
+
+  /**
+   * Get words array
+   * @param {string} text - Text to split
+   * @returns {string[]} Array of words
+   */
+  getWords(text) {
+    return text
+      .replace(/[#*`\[\]()]/g, ' ')
+      .split(/\s+/)
+      .filter(w => w.length > 0);
+  }
+
+  /**
+   * Get letter grade from score
+   * @param {number} score - SEO score
+   * @returns {string} Letter grade
+   */
+  getGrade(score) {
+    if (score >= 90) return 'A';
+    if (score >= 80) return 'B';
+    if (score >= 70) return 'C';
+    if (score >= 60) return 'D';
+    return 'F';
+  }
+}
+
+// Factory function
+export function createSEOOptimizer(options) {
+  return new SEOOptimizer(options);
+}
+
+export default SEOOptimizer;