gsc-cli 2.1.0 → 2.2.2

data/lib/gsc/geo_auditor.rb

@@ -0,0 +1,368 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'zlib'
+require 'stringio'
+
+module GSC
+  class GeoAuditor
+    AI_BOTS = {
+      'GPTBot'             => { provider: 'OpenAI (ChatGPT Search)', critical: true },
+      'ClaudeBot'          => { provider: 'Anthropic (Claude AI)', critical: true },
+      'PerplexityBot'      => { provider: 'Perplexity AI Search', critical: true },
+      'Google-Extended'    => { provider: 'Google (Gemini & AI Overviews)', critical: true },
+      'Applebot-Extended'  => { provider: 'Apple Intelligence', critical: false },
+      'CCBot'              => { provider: 'Common Crawl (Open LLM Datasets)', critical: false }
+    }.freeze
+
+    QUESTION_HEADING_REGEX = /\b(what|why|how|can|does|is|are|which|best|vs|versus|difference|guide|review|pricing|steps|definition)\b/i
+
+    attr_reader :url, :html, :http_status, :headers, :response_time_ms
+
+    def initialize(url_or_domain)
+      raw = url_or_domain.to_s.strip
+      raw = "https://#{raw}" unless raw =~ %r{^https?://}
+      @url = raw
+      @uri = URI.parse(@url)
+    end
+
+    def audit
+      fetch_page
+      return { error: true, message: "HTTP #{@http_status} fetching #{@url}" } unless @http_status == 200 && !@html.empty?
+
+      ai_crawler_status = audit_ai_crawlers
+      answer_density    = audit_direct_answers
+      fact_density      = audit_factual_citability
+      entity_authority  = audit_entity_schema
+      temporal_freshness = audit_freshness
+
+      # Scoring (0-100)
+      crawler_score = calculate_crawler_score(ai_crawler_status)
+      answer_score  = calculate_answer_score(answer_density)
+      fact_score    = calculate_fact_score(fact_density)
+      entity_score  = calculate_entity_score(entity_authority)
+
+      total_score = crawler_score + answer_score + fact_score + entity_score
+
+      recommendations = generate_recommendations(
+        ai_crawler_status,
+        answer_density,
+        fact_density,
+        entity_authority,
+        temporal_freshness
+      )
+
+      {
+        url: @url,
+        score: total_score,
+        grade: score_grade(total_score),
+        category_scores: {
+          ai_bot_access: { score: crawler_score, max: 25 },
+          direct_answers: { score: answer_score, max: 25 },
+          facts_and_data: { score: fact_score, max: 25 },
+          entity_schema: { score: entity_score, max: 25 }
+        },
+        ai_crawlers: ai_crawler_status,
+        direct_answers: answer_density,
+        facts_and_citability: fact_density,
+        entity_knowledge_graph: entity_authority,
+        freshness: temporal_freshness,
+        recommendations: recommendations
+      }
+    end
+
+    private
+
+    def fetch_page
+      start_t = Time.now
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = (@uri.scheme == 'https')
+      http.open_timeout = 8
+      http.read_timeout = 15
+
+      req = Net::HTTP::Get.new(@uri.request_uri.empty? ? '/' : @uri.request_uri)
+      req['User-Agent'] = "Mozilla/5.0 (compatible; GSC-GEO-Auditor/#{GSC::VERSION}; +https://apolloswave.com)"
+      req['Accept-Encoding'] = 'gzip'
+
+      res = http.request(req)
+      @response_time_ms = ((Time.now - start_t) * 1000).round(1)
+      @http_status = res.code.to_i
+      @headers = res.to_hash
+
+      raw_body = res.body || ''
+      body_str = if res['content-encoding'] =~ /gzip/i && !raw_body.empty?
+                   begin
+                     Zlib::GzipReader.new(StringIO.new(raw_body)).read
+                   rescue StandardError
+                     raw_body
+                   end
+                 else
+                   raw_body
+                 end
+      @html = body_str.to_s.dup.force_encoding('UTF-8').scrub
+    rescue StandardError => e
+      @http_status = 0
+      @html = ''
+      @error_msg = e.message
+    end
+
+    def audit_ai_crawlers
+      robots_url = "#{@uri.scheme}://#{@uri.host}:#{@uri.port}/robots.txt"
+      robots_txt = ''
+      begin
+        res = Net::HTTP.get_response(URI.parse(robots_url))
+        robots_txt = res.body.to_s.dup.force_encoding('UTF-8').scrub if res.code == '200'
+      rescue StandardError
+        robots_txt = ''
+      end
+
+      # Check robots meta in page
+      robots_meta = @html[/<meta\s+[^>]*name=['"]robots['"][^>]*content=['"]([^'"]+)['"]/i, 1] || ''
+      noindex = robots_meta =~ /noindex/i
+      nosnippet = robots_meta =~ /nosnippet/i
+
+      checker = RobotsChecker.new(@url)
+      bot_results = {}
+
+      AI_BOTS.each do |bot_name, meta|
+        rule = checker.check(@uri.path, bot_name)
+        allowed = rule[:allowed] && !noindex
+        bot_results[bot_name] = {
+          provider: meta[:provider],
+          allowed: allowed,
+          critical: meta[:critical],
+          rule: rule[:matched_rule] ? "#{rule[:matched_rule][:type]}: #{rule[:matched_rule][:path]}" : 'Default (Allowed)'
+        }
+      end
+
+      {
+        robots_txt_found: !robots_txt.empty?,
+        meta_noindex: !!noindex,
+        meta_nosnippet: !!nosnippet,
+        bots: bot_results,
+        all_critical_allowed: bot_results.select { |_, v| v[:critical] }.all? { |_, v| v[:allowed] }
+      }
+    end
+
+    def audit_direct_answers
+      # Find headings that look like user questions
+      headings = []
+      @html.scan(/<(h[23])[^>]*>(.*?)<\/\1>/im) do |tag, text|
+        clean = text.gsub(/<[^>]+>/, '').strip
+        next if clean.empty?
+
+        is_question = (clean =~ QUESTION_HEADING_REGEX) || clean.end_with?('?')
+        headings << { tag: tag, text: clean, is_question: !!is_question }
+      end
+
+      # Analyze paragraphs following question headings
+      answer_blocks = []
+      headings.select { |h| h[:is_question] }.each do |h|
+        pattern = /<#{h[:tag]}[^>]*>#{Regexp.escape(h[:text])}<\/#{h[:tag]}>\s*<p[^>]*>(.*?)<\/p>/im
+        match = @html[pattern, 1]
+        if match
+          ans_text = match.gsub(/<[^>]+>/, '').strip
+          words = ans_text.split(/\s+/).size
+          # Ideal direct answer for LLM citation is 30-80 words
+          optimal = words >= 30 && words <= 80
+          answer_blocks << {
+            question: h[:text],
+            answer_preview: ans_text[0..120] + (ans_text.length > 120 ? '...' : ''),
+            word_count: words,
+            optimal_length: optimal
+          }
+        end
+      end
+
+      {
+        total_question_headings: headings.count { |h| h[:is_question] },
+        direct_answer_blocks_found: answer_blocks.size,
+        optimal_answers_count: answer_blocks.count { |a| a[:optimal_length] },
+        samples: answer_blocks.first(3)
+      }
+    end
+
+    def audit_factual_citability
+      clean = @html.gsub(/<script\b[^>]*>.*?<\/script>/im, ' ')
+                   .gsub(/<style\b[^>]*>.*?<\/style>/im, ' ')
+
+      # Count statistical data points
+      percentages = clean.scan(/\b\d+(?:\.\d+)?%/).size
+      currency_points = clean.scan(/(?:\$|€|£)\s*\d+(?:,\d{3})*(?:\.\d+)?/).size
+      numbers = clean.scan(/\b\d+(?:,\d{3})+(?:\.\d+)?\b/).size
+      recent_years = clean.scan(/\b(202[4-6])\b/).size
+
+      # Count structured list items
+      list_items = clean.scan(/<li\b[^>]*>(.*?)<\/li>/im).size
+
+      # Count table rows
+      table_rows = clean.scan(/<tr\b[^>]*>/im).size
+
+      {
+        percentage_mentions: percentages,
+        currency_mentions: currency_points,
+        large_numbers: numbers,
+        recent_year_mentions: recent_years,
+        bullet_list_items: list_items,
+        comparison_table_rows: table_rows,
+        high_fact_density: (percentages + currency_points + numbers >= 5) || (list_items >= 6)
+      }
+    end
+
+    def audit_entity_schema
+      schemas = []
+      @html.scan(/<script\s+[^>]*type=['"]application\/ld\+json['"][^>]*>(.*?)<\/script>/im) do |m|
+        content = m.first.to_s.strip
+        begin
+          parsed = JSON.parse(content)
+          schemas.concat(parsed.is_a?(Array) ? parsed : [parsed])
+        rescue StandardError
+          nil
+        end
+      end
+
+      types = schemas.map { |s| s['@type'] }.compact.flatten
+      same_as = []
+      author_info = nil
+      brand_info = nil
+
+      schemas.each do |s|
+        same_as.concat(Array(s['sameAs'])) if s['sameAs']
+        author_info ||= s['author'] if s['author']
+        brand_info ||= (s['brand'] || s['name']) if %w[Organization Brand WebSite Product].include?(s['@type'])
+      end
+
+      same_as_domains = same_as.map do |link|
+        begin
+          URI.parse(link.to_s).host
+        rescue StandardError
+          link.to_s
+        end
+      end.compact.uniq
+
+      has_wiki = same_as_domains.any? { |d| d =~ /wikipedia|wikidata/i }
+      has_social_entity = same_as_domains.any? { |d| d =~ /linkedin|twitter|x\.com|youtube|github/i }
+
+      {
+        schema_count: schemas.size,
+        schema_types: types.uniq,
+        has_organization_or_brand: types.any? { |t| %w[Organization Brand WebSite].include?(t) },
+        has_faq_or_howto: types.any? { |t| %w[FAQPage HowTo QAPage].include?(t) },
+        has_article_schema: types.any? { |t| %w[Article NewsArticle BlogPosting TechArticle].include?(t) },
+        has_author: !author_info.nil?,
+        same_as_links_count: same_as.size,
+        same_as_domains: same_as_domains,
+        wikidata_or_wikipedia_linked: has_wiki,
+        social_entity_linked: has_social_entity
+      }
+    end
+
+    def audit_freshness
+      published = @html[/<meta\s+[^>]*property=['"]article:published_time['"][^>]*content=['"]([^'"]+)['"]/i, 1] ||
+                  @html[/<meta\s+[^>]*name=['"]pubdate['"][^>]*content=['"]([^'"]+)['"]/i, 1]
+      modified  = @html[/<meta\s+[^>]*property=['"]article:modified_time['"][^>]*content=['"]([^'"]+)['"]/i, 1] ||
+                  @html[/<meta\s+[^>]*name=['"]last-modified['"][^>]*content=['"]([^'"]+)['"]/i, 1]
+
+      {
+        published_date: published,
+        modified_date: modified,
+        has_dates: !published.nil? || !modified.nil?
+      }
+    end
+
+    def calculate_crawler_score(ai_crawlers)
+      score = 0
+      critical_bots = ai_crawlers[:bots].select { |_, b| b[:critical] }
+      allowed_count = critical_bots.count { |_, b| b[:allowed] }
+
+      score += (allowed_count.to_f / [critical_bots.size, 1].max * 20).round
+      score += 5 unless ai_crawlers[:meta_nosnippet] || ai_crawlers[:meta_noindex]
+      score
+    end
+
+    def calculate_answer_score(answers)
+      score = 0
+      score += 8 if answers[:total_question_headings] >= 2
+      score += 10 if answers[:direct_answer_blocks_found] >= 2
+      score += 7 if answers[:optimal_answers_count] >= 1
+      [score, 25].min
+    end
+
+    def calculate_fact_score(facts)
+      score = 0
+      score += 8 if (facts[:percentage_mentions] + facts[:currency_mentions] + facts[:large_numbers]) >= 3
+      score += 9 if facts[:bullet_list_items] >= 5
+      score += 5 if facts[:recent_year_mentions] >= 1
+      score += 3 if facts[:comparison_table_rows] >= 2
+      [score, 25].min
+    end
+
+    def calculate_entity_score(entity)
+      score = 0
+      score += 7 if entity[:has_organization_or_brand]
+      score += 7 if entity[:has_faq_or_howto] || entity[:has_article_schema]
+      score += 6 if entity[:same_as_links_count] >= 1
+      score += 5 if entity[:wikidata_or_wikipedia_linked] || entity[:social_entity_linked]
+      [score, 25].min
+    end
+
+    def score_grade(score)
+      case score
+      when 85..100 then 'A (Exceptional AI Search Citability)'
+      when 70..84  then 'B (Good - Minor Entity & Direct Answer Gaps)'
+      when 50..69  then 'C (Moderate - Missing Key AI Bot Access or Schema)'
+      else              'D/F (Poor - High Risk of Being Ignored by LLMs)'
+      end
+    end
+
+    def generate_recommendations(crawlers, answers, facts, entity, freshness)
+      recs = []
+
+      # AI Crawlers
+      blocked = crawlers[:bots].select { |_, b| !b[:allowed] }
+      if blocked.any?
+        names = blocked.keys.join(', ')
+        recs << "Unblock #{names} in /robots.txt to permit ChatGPT, Claude, and Perplexity from quoting this URL."
+      end
+      if crawlers[:meta_nosnippet]
+        recs << "Remove 'nosnippet' directive from robots meta tag; LLMs require snippet extraction to cite your content."
+      end
+
+      # Direct Answers
+      if answers[:direct_answer_blocks_found] == 0
+        recs << "Add 2+ question headings (H2/H3 'What is...', 'How to...') followed immediately by a concise 40-60 word definition paragraph."
+      elsif answers[:optimal_answers_count] == 0
+        recs << "Tighten paragraph lengths following question headings to 40-70 words. Overly long prose reduces LLM snippet selection."
+      end
+
+      # Factual Citability
+      if !facts[:high_fact_density]
+        recs << "Inject concrete statistics (percentages, metrics, pricing) and bulleted key takeaways; LLMs favor citing verified data points over generic prose."
+      end
+      if facts[:bullet_list_items] < 4
+        recs << "Add structured bulleted summaries (<ul>/<li>) beneath major section headers for easy machine extraction."
+      end
+
+      # Entity Schema
+      if !entity[:has_organization_or_brand]
+        recs << "Add JSON-LD 'Organization' or 'Brand' structured data with official entity name and logo."
+      end
+      if entity[:same_as_links_count] == 0
+        recs << "Add 'sameAs' links inside your Organization JSON-LD pointing to Wikipedia, Wikidata, LinkedIn, or Twitter/X to disambiguate your brand in LLM Knowledge Graphs."
+      end
+      if !entity[:has_faq_or_howto]
+        recs << "Implement FAQPage JSON-LD schema wrapping your common questions and answers."
+      end
+
+      # Freshness
+      unless freshness[:has_dates]
+        recs << "Include visible publication and modification dates (and 'datePublished'/'dateModified' in schema) to signal content freshness to AI answer engines."
+      end
+
+      recs
+    end
+  end
+end

data/lib/gsc/google_trends.rb

@@ -63,7 +63,14 @@ class GoogleTrends
     explore_req['Cookie'] = cookies if cookies
 
     explore_res = http.request(explore_req)
-    return { ok: false, error: "Google Trends Explore API error (HTTP #{explore_res.code})" } unless explore_res.is_a?(Net::HTTPSuccess)
+    if explore_res.code == '302'
+      loc = explore_res['location'].to_s
+      return { ok: false, error: "Google Trends rate limit or bot challenge triggered (HTTP 302 redirect to #{loc.include?('sorry') ? 'Google CAPTCHA' : 'redirect'}). Google is temporarily throttling Trends requests from this network. Try again in a few minutes, or use 'gsc suggest' / 'gsc planner'." }
+    elsif explore_res.code == '429' || init_res.code == '429'
+      return { ok: false, error: "Google Trends rate limit reached (HTTP 429 - Too Many Requests). Google is temporarily throttling Trends requests from this network. Try again in a few minutes, or use 'gsc suggest' / 'gsc planner'." }
+    elsif !explore_res.is_a?(Net::HTTPSuccess)
+      return { ok: false, error: "Google Trends Explore API error (HTTP #{explore_res.code})" }
+    end
 
     raw_exp = explore_res.body.to_s
     clean_body = raw_exp.index('{') ? raw_exp[raw_exp.index('{')..] : raw_exp

data/lib/gsc/heading_validator.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module GSC
+  class HeadingValidator
+    attr_reader :headings, :counts, :violations, :score, :grade, :depth
+
+    def self.analyze(html, target_keywords: nil)
+      new(html, target_keywords: target_keywords).audit
+    end
+
+    def initialize(html, target_keywords: nil)
+      @html = html.to_s.dup.force_encoding('UTF-8').scrub
+      @target_keywords = extract_keyword_tokens(target_keywords)
+      @headings = []
+      @counts = { 'h1' => 0, 'h2' => 0, 'h3' => 0, 'h4' => 0, 'h5' => 0, 'h6' => 0 }
+      @violations = []
+      @score = 100
+      @grade = 'A'
+      @depth = 0
+    end
+
+    def audit
+      parse_headings!
+      validate_hierarchy!
+      calculate_score!
+      audit_keywords! if @target_keywords && !@target_keywords.empty?
+
+      {
+        score: @score,
+        grade: @grade,
+        depth: @depth,
+        count: @headings.size,
+        counts: @counts,
+        h1_count: @counts['h1'],
+        empty_count: @headings.count { |h| h[:empty] },
+        headings: @headings,
+        violations: @violations,
+        keyword_analysis: @keyword_analysis,
+        summary: summary_text,
+        ascii_tree: render_ascii_tree(colorize: false),
+        color_tree: render_ascii_tree(colorize: true)
+      }
+    end
+
+    def render_ascii_tree(colorize: false)
+      return '   (No headings found on page)' if @headings.empty?
+
+      lines = []
+      @headings.each_with_index do |h, idx|
+        level = h[:level]
+        tag_str = "[#{h[:tag].upcase}]"
+        prefix = '   ' + ('  ' * (level - 1)) + (level == 1 ? '■ ' : '├── ')
+
+        text_str = h[:empty] ? '(Empty Heading Tag)' : h[:text]
+        # Truncate very long heading in display
+        display_text = text_str.length > 75 ? "#{text_str[0..72]}..." : text_str
+
+        # Check if this heading has an attached violation
+        v_msgs = h[:violations].map { |v| v[:message] }
+        v_suffix = v_msgs.empty? ? '' : " ⚠️  #{v_msgs.join('; ')}"
+
+        if colorize && defined?(Color)
+          tag_color = case level
+                      when 1 then Color::CYAN
+                      when 2 then Color::BLUE
+                      when 3 then Color::MAGENTA
+                      else Color::GRAY
+                      end
+          colored_tag = Color.c(tag_str, tag_color, Color::BOLD)
+          colored_text = h[:empty] ? Color.c(display_text, Color::RED, Color::DIM) : display_text
+          colored_suffix = v_suffix.empty? ? '' : Color.c(v_suffix, Color::YELLOW, Color::BOLD)
+          lines << "#{prefix}#{colored_tag} #{colored_text}#{colored_suffix}"
+        else
+          lines << "#{prefix}#{tag_str} #{display_text}#{v_suffix}"
+        end
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    def parse_headings!
+      idx = 0
+      @html.scan(%r{<(h[1-6])(?:\s+[^>]*)?>(.*?)</\1>}im) do |tag, content|
+        idx += 1
+        clean = clean_text(content)
+        level = tag[1].to_i
+        is_empty = clean.empty?
+
+        h_info = {
+          index: idx,
+          tag: tag.downcase,
+          level: level,
+          text: clean,
+          length: clean.length,
+          empty: is_empty,
+          violations: []
+        }
+
+        @headings << h_info
+        @counts[tag.downcase] += 1
+        @depth = level if level > @depth
+      end
+    end
+
+    def validate_hierarchy!
+      return if @headings.empty?
+
+      # 1. Check if first heading is H1
+      first_h = @headings.first
+      if first_h[:level] != 1
+        v = {
+          type: :first_not_h1,
+          severity: :warning,
+          tag: first_h[:tag],
+          index: 1,
+          message: "Page starts with <#{first_h[:tag]}> instead of <h1>"
+        }
+        @violations << v
+        first_h[:violations] << v
+      end
+
+      # 2. Check H1 count
+      if @counts['h1'] == 0
+        @violations << {
+          type: :missing_h1,
+          severity: :critical,
+          message: 'Missing <h1> tag. Document has 0 top-level headings.'
+        }
+      elsif @counts['h1'] > 1
+        extra_h1s = @headings.select { |h| h[:tag] == 'h1' }[1..]
+        extra_h1s.each do |eh|
+          v = {
+            type: :multiple_h1,
+            severity: :warning,
+            tag: 'h1',
+            index: eh[:index],
+            message: "Multiple <h1> tag detected at position ##{eh[:index]} ('#{eh[:text][0..40]}...')"
+          }
+          @violations << v
+          eh[:violations] << v
+        end
+      end
+
+      # 3. Check sequential depth skips (e.g. H1 -> H3 or H2 -> H4)
+      prev_level = nil
+      @headings.each do |h|
+        curr_level = h[:level]
+
+        if prev_level && curr_level > prev_level + 1
+          skipped = (prev_level + 1...curr_level).map { |lvl| "<h#{lvl}>" }.join(', ')
+          v = {
+            type: :skipped_level,
+            severity: :warning,
+            tag: h[:tag],
+            index: h[:index],
+            from_level: prev_level,
+            to_level: curr_level,
+            message: "Skipped heading level: jumped from <h#{prev_level}> to <h#{curr_level}> (skipped #{skipped})"
+          }
+          @violations << v
+          h[:violations] << v
+        end
+
+        # 4. Check empty heading
+        if h[:empty]
+          v = {
+            type: :empty_heading,
+            severity: :error,
+            tag: h[:tag],
+            index: h[:index],
+            message: "Empty <#{h[:tag]}> tag with no text content"
+          }
+          @violations << v
+          h[:violations] << v
+        end
+
+        # 5. Check overlong heading (> 80 chars)
+        if h[:length] > 80
+          v = {
+            type: :overlong_heading,
+            severity: :info,
+            tag: h[:tag],
+            index: h[:index],
+            message: "Heading length (#{h[:length]} chars) exceeds 80 chars; risk of topical dilution"
+          }
+          @violations << v
+          h[:violations] << v
+        end
+
+        prev_level = curr_level
+      end
+    end
+
+    def calculate_score!
+      if @headings.empty?
+        @score = 0
+        @grade = 'F'
+        return
+      end
+
+      deductions = 0
+      @violations.each do |v|
+        deductions += case v[:type]
+                      when :missing_h1 then 30
+                      when :multiple_h1 then 15
+                      when :skipped_level then 10
+                      when :empty_heading then 10
+                      when :first_not_h1 then 10
+                      when :overlong_heading then 5
+                      else 5
+                      end
+      end
+
+      @score = [100 - deductions, 0].max
+      @grade = case @score
+               when 90..100 then 'A'
+               when 80..89  then 'B'
+               when 70..79  then 'C'
+               when 60..69  then 'D'
+               else 'F'
+               end
+    end
+
+    def audit_keywords!
+      h1 = @headings.find { |h| h[:tag] == 'h1' }
+      h1_matches = []
+      if h1
+        h1_text = h1[:text].downcase
+        h1_matches = @target_keywords.select { |kw| h1_text.include?(kw) }
+      end
+
+      h2_matches = {}
+      @headings.select { |h| h[:tag] == 'h2' }.each do |h2|
+        h2_text = h2[:text].downcase
+        matched = @target_keywords.select { |kw| h2_text.include?(kw) }
+        h2_matches[h2[:text]] = matched unless matched.empty?
+      end
+
+      @keyword_analysis = {
+        target_keywords: @target_keywords,
+        h1_has_keyword: !h1_matches.empty?,
+        h1_matched_keywords: h1_matches,
+        h2_matched_count: h2_matches.size,
+        h2_matches: h2_matches
+      }
+    end
+
+    def extract_keyword_tokens(keywords)
+      return [] if keywords.nil? || keywords.to_s.strip.empty?
+
+      if keywords.is_a?(Array)
+        keywords.map { |k| k.to_s.downcase.strip }.reject(&:empty?)
+      else
+        keywords.to_s.downcase.split(/[,|\s]+/).map(&:strip).reject { |w| w.length < 3 }
+      end
+    end
+
+    def clean_text(str)
+      str.to_s
+         .dup
+         .force_encoding('UTF-8')
+         .scrub
+         .gsub(/<[^>]+>/, ' ')
+         .gsub(/&amp;/, '&')
+         .gsub(/&lt;/, '<')
+         .gsub(/&gt;/, '>')
+         .gsub(/&quot;/, '"')
+         .gsub(/&#39;/, "'")
+         .gsub(/&nbsp;/, ' ')
+         .gsub(/\s+/, ' ')
+         .strip
+    end
+
+    def summary_text
+      counts_str = @counts.select { |_k, v| v > 0 }.map { |k, v| "#{v}x #{k.upcase}" }.join(', ')
+      "Heading Health Score: #{@score}/100 (Grade #{@grade}) | Depth: H#{@depth} | Total: #{@headings.size} (#{counts_str}) | #{@violations.size} violations"
+    end
+  end
+end