crawlscope 0.8.0 → 0.9.0

data/lib/crawlscope/reporter.rb

@@ -4,7 +4,37 @@ require "uri"
 
 module Crawlscope
   class Reporter
-    MAX_ISSUES_PER_GROUP = 20
+    GROUP_LABELS = {
+      structured_data_schema_error: "Schema errors",
+      structured_data_parse_error: "Parse errors",
+      structured_data_missing_type: "Missing @type",
+      sitemap_redirect_url: "Redirected URLs",
+      non_canonical_page_in_sitemap: "URLs with a different canonical",
+      indexable_page_missing_from_sitemap: "Linked pages missing from sitemap",
+      sitemap_noindex_url: "URLs that block indexing",
+      low_dofollow_inlinks: "Too few incoming links without nofollow",
+      low_inbound_anchor_links: "Too few incoming links",
+      low_unique_token_ratio: "Repeated words",
+      low_visible_text_ratio: "Too little text for the HTML size",
+      thin_visible_text: "Too few words",
+      orphan_page: "Pages with no incoming links",
+      nofollow_internal_outlinks: "Outgoing links with nofollow",
+      only_nofollow_internal_inlinks: "Incoming links all use nofollow",
+      mixed_follow_internal_inlinks: "Incoming links with and without nofollow",
+      http_internal_link: "Links from HTTPS to HTTP",
+      canonical_no_internal_inlinks: "Canonical URLs with no incoming links without nofollow",
+      canonical_points_to_error: "Canonical URLs that return errors",
+      url_double_slash: "Repeated slashes in URL paths",
+      multiple_h1: "Multiple <h1> tags",
+      multiple_title_tags: "Multiple <title> tags",
+      incomplete_open_graph_tags: "Missing Open Graph tags",
+      title_too_long: "Title exceeds #{Rules::Metadata::TITLE_MAX_LENGTH} characters",
+      meta_description_too_long: "Meta description exceeds #{Rules::Metadata::DESCRIPTION_MAX_LENGTH} characters",
+      meta_description_too_short: "Meta description below #{Rules::Metadata::DESCRIPTION_MIN_LENGTH} characters",
+      duplicate_content_fingerprint: "Duplicate page text",
+      near_duplicate_content: "Similar page text",
+      near_duplicate_scan_skipped: "Similar-page check skipped"
+    }.freeze
 
     def initialize(io:)
       @io = io
@@ -24,16 +54,12 @@ module Crawlscope
         @io.puts("Issues: #{result.issues.size} total (#{severity_summary(result.issues)})")
       end
 
-      ServerTiming::Reporter.new(io: @io).report(
-        result.server_timing_summary,
-        base_url: result.base_url
-      )
-      return if result.issues.size.zero?
+      unless result.issues.size.zero?
+        @io.puts("")
+        report_issue_groups(result.issues, base_url: result.base_url)
+      end
 
-      @io.puts("")
-      report_summary(result.issues)
-      @io.puts("")
-      report_issue_groups(result.issues, base_url: result.base_url)
+      ServerTiming::Reporter.new(io: @io).report(result.server_timing_summary, base_url: result.base_url)
     end
 
     private
@@ -51,43 +77,45 @@ module Crawlscope
     end
 
     def severity_summary(issues)
-      grouped = issues.by_severity
-      return "" if grouped.empty?
-
-      grouped
-        .sort_by { |severity, severity_issues| [-severity_issues.size, severity.to_s] }
-        .map { |severity, severity_issues| "#{severity_issues.size} #{pluralize(severity, severity_issues.size)}" }
-        .join(", ")
-    end
-
-    def report_summary(issues)
-      @io.puts("Summary:")
-
-      issues.by_category
-        .sort_by { |category, category_issues| [-category_issues.size, category.to_s] }
-        .each do |category, category_issues|
-          @io.puts("  #{category.to_s.ljust(16)} #{category_issues.size}")
-        end
+      severity_summary_for(issues.to_a)
     end
 
     def report_issue_groups(issues, base_url:)
       grouped = issues.to_a.group_by { |issue| [issue.category, issue.code] }
 
       grouped
-        .sort_by { |(category, code), grouped_issues| [-grouped_issues.size, category.to_s, code.to_s] }
+        .sort_by { |(category, code), grouped_issues| [grouped_issues.map { |issue| severity_order(issue.severity) }.min, -grouped_issues.size, category.to_s, code.to_s] }
         .each do |(category, code), grouped_issues|
-          @io.puts("#{category} / #{code}: #{grouped_issues.size}")
-
-          grouped_issues.first(MAX_ISSUES_PER_GROUP).each do |issue|
-            @io.puts("  - #{compact_issue(issue, base_url: base_url)}")
+          label = GROUP_LABELS.fetch(code) { code.to_s.tr("_", " ").capitalize }
+          @io.puts("#{category.to_s.tr("_", " ").capitalize}: #{label} (#{severity_summary_for(grouped_issues)})")
+
+          grouped_issues.each do |issue|
+            details = issue.details || {}
+            if issue.code == :structured_data_schema_error && details[:errors]&.any?
+              source = (details[:source] == "json-ld") ? "JSON-LD" : details[:source]
+              @io.puts("  - #{relative_url(issue.url, base_url: base_url)}  #{source}")
+              details[:errors].each do |error|
+                @io.puts("      #{StructuredData::ErrorFormatter.format(error)}")
+              end
+            else
+              @io.puts("  - #{compact_issue(issue, base_url: base_url)}")
+              report_related_urls(issue, details, base_url: base_url)
+            end
           end
 
-          remaining_count = grouped_issues.size - MAX_ISSUES_PER_GROUP
-          @io.puts("  ... #{remaining_count} more") if remaining_count.positive?
           @io.puts("")
         end
     end
 
+    def severity_order(severity)
+      {error: 0, warning: 1, notice: 2}.fetch(severity, 3)
+    end
+
+    def severity_summary_for(issues)
+      issues.group_by(&:severity).sort_by { |severity, _| severity_order(severity) }
+        .map { |severity, entries| "#{entries.size} #{pluralize(severity, entries.size)}" }.join(", ")
+    end
+
     def compact_issue(issue, base_url:)
       parts = []
       parts << relative_url(issue.url, base_url: base_url) if issue.url
@@ -100,35 +128,87 @@ module Crawlscope
 
     def compact_detail(issue, base_url:)
       details = issue.details || {}
-      fragments = []
-
-      inbound = details[:dofollow_inbound_count] || details[:inbound_count]
-      fragments << "inbound #{inbound}/#{details[:minimum]}" if inbound && details[:minimum]
-
-      if details[:ratio] && details[:threshold]
-        fragments << "ratio #{format_number(details[:ratio])}/#{format_number(details[:threshold])}"
-      end
-
-      fragments << "count #{details[:count]}" if details[:count]
-      fragments << "length #{details[:length]}" if details[:length]
-      fragments << "status #{details[:status]}" if details[:status]
-      fragments << "final: #{relative_url(details[:final_url], base_url: base_url)}" if details[:final_url]
-      fragments << "sources: #{relative_urls(details[:source_urls], base_url: base_url).join(", ")}" if details[:source_urls]&.any?
-      fragments << "source: #{relative_url(details[:source_url], base_url: base_url)}" if details[:source_url]
-      fragments << "targets: #{relative_urls(details[:target_urls], base_url: base_url).join(", ")}" if details[:target_urls]&.any?
-
-      return issue.message if fragments.empty?
-
       case issue.code
-      when :low_dofollow_inlinks, :low_inbound_anchor_links, :low_unique_token_ratio, :low_visible_text_ratio
-        fragments.join("  ")
-      else
-        ([issue.message] + fragments).join("  ")
+      when :redirected_page, :sitemap_redirect_url, :internal_link_redirects
+        if details[:final_url]
+          prefix = (issue.code == :sitemap_redirect_url) ? "sitemap URL redirects to" : "redirects to"
+          status = details[:status] ? " (final HTTP #{details[:status]})" : ""
+          return "#{prefix} #{relative_url(details[:final_url], base_url: base_url)}#{status}"
+        end
+      when :canonical_mismatch, :non_canonical_page_in_sitemap
+        if details[:canonical]
+          prefix = (issue.code == :non_canonical_page_in_sitemap) ? "sitemap lists this URL, but its canonical points to" : "canonical points to a different URL:"
+          return "#{prefix} #{relative_url(details[:canonical], base_url: base_url)}"
+        end
+      when :unexpected_status
+        return "HTTP #{details[:status]}" if details[:status]
+      when :title_too_long, :meta_description_too_long, :meta_description_too_short
+        return "#{details[:length]} characters" if details[:length]
+      when :broken_internal_link
+        return "linked URL returns HTTP #{details[:status]}"
+      when :unresolved_internal_link
+        return ["cannot check linked URL", details[:error]].compact.join(": ")
+      when :indexable_page_missing_from_sitemap
+        return "linked page is missing from sitemap"
+      when :canonical_points_to_redirect
+        status = details[:status] ? " (final HTTP #{details[:status]})" : ""
+        return "canonical #{relative_url(details[:canonical], base_url: base_url)} redirects to #{relative_url(details[:final_url], base_url: base_url)}#{status}"
+      when :canonical_points_to_error
+        return "canonical #{relative_url(details[:canonical], base_url: base_url)} returns HTTP #{details[:status]}"
+      when :low_dofollow_inlinks, :low_inbound_anchor_links
+        count = details[:dofollow_inbound_count] || details[:inbound_count]
+        label = (issue.code == :low_dofollow_inlinks) ? "incoming links without nofollow" : "incoming links"
+        return "#{label}: #{count}; minimum #{details[:minimum]}"
+      when :low_unique_token_ratio, :low_visible_text_ratio
+        label = (issue.code == :low_unique_token_ratio) ? "unique words" : "visible text / HTML bytes"
+        return "#{label}: #{percentage(details[:ratio])}; minimum #{percentage(details[:threshold])}"
+      when :thin_visible_text
+        return "visible words: #{details[:word_count]}; minimum #{details[:minimum]}"
+      when :mixed_follow_internal_inlinks
+        return "incoming links: #{details[:dofollow_inbound_count]} without nofollow, #{details[:nofollow_inbound_count]} with nofollow"
+      when :only_nofollow_internal_inlinks
+        return "all #{details[:nofollow_inbound_count]} incoming internal links use nofollow"
+      when :duplicate_title, :duplicate_meta_description
+        label = (issue.code == :duplicate_title) ? "same title" : "same meta description"
+        return "#{label}: #{details[:value].to_s.inspect}"
+      when :duplicate_content_fingerprint
+        return "same page text"
+      when :duplicate_pages_without_canonical
+        return "same page text; at least one page has no canonical link"
+      when :near_duplicate_content
+        return "text similarity: #{percentage(details[:similarity])}; threshold #{percentage(details[:threshold])}"
+      when :near_duplicate_scan_skipped
+        return "similar-page check skipped: #{details[:page_count]} pages; limit #{details[:max_pages]}"
+      when :structured_data_missing_type
+        return "#{issue.message} at #{Array(details[:paths]).join(", ")}" if details[:paths]&.any?
+      when :noindex_meta, :nofollow_meta, :noindex_follow_meta, :noindex_nofollow_meta,
+          :noindex_header, :nofollow_header, :noindex_follow_header, :noindex_nofollow_header,
+          :sitemap_noindex_url
+        if details[:content]
+          source = details[:name] || details[:source]
+          label = source ? "#{source}: " : ""
+          return "#{issue.message} (#{label}#{details[:content]})"
+        end
       end
+      issue.message
     end
 
-    def relative_urls(urls, base_url:)
-      Array(urls).map { |url| relative_url(url, base_url: base_url) }
+    def report_related_urls(issue, details, base_url:)
+      source_label = (issue.code == :canonical_no_internal_inlinks) ? "canonical on" : "linked from"
+      sources = Array(details[:source_urls])
+      sources += [details[:source_url]] if details[:source_url]
+      relationships = {
+        source_label => sources.uniq,
+        "links to" => details[:target_urls],
+        "page" => details[:urls],
+        "linked from (without nofollow)" => details[:dofollow_source_urls],
+        "linked from (nofollow)" => details[:nofollow_source_urls]
+      }
+      relationships.each do |label, urls|
+        Array(urls).each do |url|
+          @io.puts("      #{label}: #{relative_url(url, base_url: base_url)}")
+        end
+      end
     end
 
     def relative_url(url, base_url:)
@@ -147,10 +227,8 @@ module Crawlscope
       url
     end
 
-    def format_number(value)
-      return format("%.3f", value) if value.is_a?(Float)
-
-      value.to_s
+    def percentage(value)
+      "#{format("%.3f", value * 100).sub(/0+\z/, "").sub(/\.\z/, "")}%"
     end
 
     def pluralize(word, count)

data/lib/crawlscope/rules/content_quality.rb

@@ -44,7 +44,7 @@ module Crawlscope
           severity: :warning,
           category: :content_quality,
           url: page.url,
-          message: "visible text has low token variety (#{format_ratio(ratio)})",
+          message: "unique words: #{format_percentage(ratio)}; minimum #{format_percentage(@min_unique_token_ratio)}",
           details: {
             ratio: ratio.round(3),
             threshold: @min_unique_token_ratio,
@@ -67,7 +67,7 @@ module Crawlscope
           severity: :warning,
           category: :content_quality,
           url: page.url,
-          message: "low visible text to HTML ratio (#{format_ratio(ratio)})",
+          message: "visible text / HTML bytes: #{format_percentage(ratio)}; minimum #{format_percentage(@min_visible_text_ratio)}",
           details: {
             html_bytes: html_bytes,
             ratio: ratio.round(3),
@@ -86,13 +86,13 @@ module Crawlscope
           severity: :warning,
           category: :content_quality,
           url: page.url,
-          message: "thin visible text (#{word_count} words)",
+          message: "visible words: #{word_count}; minimum #{@min_visible_words}",
           details: {word_count: word_count, minimum: @min_visible_words}
         )
       end
 
-      def format_ratio(value)
-        format("%.2f", value)
+      def format_percentage(value)
+        "#{format("%.3f", value * 100).sub(/0+\z/, "").sub(/\.\z/, "")}%"
       end
     end
   end

data/lib/crawlscope/rules/indexability.rb

@@ -192,7 +192,7 @@ module Crawlscope
           severity: :error,
           category: :sitemaps,
           url: page.url,
-          message: "sitemap URL is noindex",
+          message: "sitemap lists a URL that blocks indexing",
           details: {content: content, source: source}
         )
       end

data/lib/crawlscope/rules/links.rb

@@ -8,7 +8,6 @@ module Crawlscope
       LINK_SELECTORS = "a[href]"
       INTERNAL_PATH_PREFIXES_TO_SKIP = ["/rails/", "/cdn-cgi/"].freeze
       LINK_SCHEMES_TO_SKIP = ["mailto:", "tel:", "javascript:", "data:"].freeze
-      MAX_SOURCES_IN_ERROR = 3
       MIN_INBOUND_ANCHOR_LINKS = 1
       MIN_DOFOLLOW_INBOUND_LINKS = 2
 
@@ -128,20 +127,20 @@ module Crawlscope
       end
 
       def report_broken_target(target_url, grouped_links, issues, status)
-        source_urls = grouped_links.map { |link| link[:source_url] }.uniq.first(MAX_SOURCES_IN_ERROR)
+        source_urls = grouped_links.map { |link| link[:source_url] }.uniq
         issues.add(
           code: :broken_internal_link,
           severity: :warning,
           category: :links,
           url: target_url,
-          message: "broken internal link (HTTP #{status}, sources: #{source_urls.join(", ")})",
+          message: "linked URL returns HTTP #{status}",
           details: {source_urls: source_urls, status: status}
         )
       end
 
       def validate_nofollow_outgoing_links(links, issues)
         links.select { |link| link[:nofollow] }.group_by { |link| link[:source_url] }.each do |source_url, grouped_links|
-          target_urls = grouped_links.map { |link| link[:target_url] }.uniq.first(MAX_SOURCES_IN_ERROR)
+          target_urls = grouped_links.map { |link| link[:target_url] }.uniq
 
           issues.add(
             code: :nofollow_internal_outlinks,
@@ -156,7 +155,7 @@ module Crawlscope
 
       def validate_http_internal_links(links, issues)
         links.select { |link| link[:http_internal_link] }.group_by { |link| link[:source_url] }.each do |source_url, grouped_links|
-          target_urls = grouped_links.map { |link| link[:target_url] }.uniq.first(MAX_SOURCES_IN_ERROR)
+          target_urls = grouped_links.map { |link| link[:target_url] }.uniq
 
           issues.add(
             code: :http_internal_link,
@@ -170,15 +169,15 @@ module Crawlscope
       end
 
       def report_unresolved_target(target_url, grouped_links, issues, resolution)
-        source_urls = grouped_links.map { |link| link[:source_url] }.uniq.first(MAX_SOURCES_IN_ERROR)
-        suffix = (resolution && resolution[:error]) ? " (#{resolution[:error]})" : ""
+        source_urls = grouped_links.map { |link| link[:source_url] }.uniq
+        suffix = (resolution && resolution[:error]) ? ": #{resolution[:error]}" : ""
 
         issues.add(
           code: :unresolved_internal_link,
           severity: :warning,
           category: :links,
           url: target_url,
-          message: "unable to validate internal link#{suffix} (sources: #{source_urls.join(", ")})",
+          message: "cannot check linked URL#{suffix}",
           details: {error: resolution && resolution[:error], source_urls: source_urls}
         )
       end
@@ -218,13 +217,13 @@ module Crawlscope
       end
 
       def report_redirect_target(target_url, grouped_links, issues, target)
-        source_urls = grouped_links.map { |link| link[:source_url] }.uniq.first(MAX_SOURCES_IN_ERROR)
+        source_urls = grouped_links.map { |link| link[:source_url] }.uniq
         issues.add(
           code: :internal_link_redirects,
           severity: :warning,
           category: :links,
           url: target_url,
-          message: "internal link redirects to #{target.final_url} (sources: #{source_urls.join(", ")})",
+          message: "internal link redirects to #{target.final_url}",
           details: {final_url: target.final_url, source_urls: source_urls, status: target.status}
         )
       end
@@ -361,15 +360,14 @@ module Crawlscope
           report_orphan_page(target_url, issues) if inbound_count.zero?
 
           if inbound_count.positive? && inbound_count < MIN_INBOUND_ANCHOR_LINKS
-            source_samples = sample_sources_by_target[path].first(MAX_SOURCES_IN_ERROR)
-            source_info = source_samples.any? ? " (sources: #{source_samples.join(", ")})" : ""
+            source_samples = sample_sources_by_target[path]
 
             issues.add(
               code: :low_inbound_anchor_links,
               severity: :warning,
               category: :links,
               url: target_url,
-              message: "inbound anchor links #{inbound_count} below #{MIN_INBOUND_ANCHOR_LINKS}#{source_info}",
+              message: "incoming internal links: #{inbound_count}; minimum #{MIN_INBOUND_ANCHOR_LINKS}",
               details: {inbound_count: inbound_count, minimum: MIN_INBOUND_ANCHOR_LINKS, source_urls: source_samples}
             )
           end
@@ -414,7 +412,7 @@ module Crawlscope
           severity: :notice,
           category: :url,
           url: url,
-          message: "URL too long (#{url.length})",
+          message: "URL: #{url.length} characters; maximum 2048",
           details: {length: url.length, maximum: 2_048}
         )
       end
@@ -446,27 +444,22 @@ module Crawlscope
 
       def validate_indexable_pages_missing_from_sitemap(urls, resolved_links, issues)
         sitemap_urls = urls.map { |url| Url.normalize(url, base_url: @base_url) }.compact.to_set
-        reported_urls = Set.new
-
-        resolved_links.each do |link|
-          final_url = link[:final_url]
+        resolved_links.group_by { |link| link[:final_url] }.each do |final_url, grouped_links|
+          link = grouped_links.first
           next if sitemap_urls.include?(final_url)
-          next if reported_urls.include?(final_url)
           next unless crawlable_path?(link[:final_path])
 
           target = target_for(final_url)
           next unless target.allowed?(@allowed_statuses) && target.html?
           next if target.noindex?
 
-          reported_urls << final_url
-
           issues.add(
             code: :indexable_page_missing_from_sitemap,
             severity: :warning,
             category: :sitemaps,
             url: final_url,
-            message: "indexable internal page is missing from sitemap",
-            details: {source_url: link[:source_url]}
+            message: "linked page is missing from sitemap",
+            details: {source_url: link[:source_url], source_urls: grouped_links.map { |entry| entry[:source_url] }.uniq}
           )
         end
       end
@@ -486,15 +479,14 @@ module Crawlscope
         return if dofollow_count.zero?
         return if dofollow_count >= MIN_DOFOLLOW_INBOUND_LINKS
 
-        source_samples = sources_by_target[path].first(MAX_SOURCES_IN_ERROR)
-        source_info = source_samples.any? ? " (sources: #{source_samples.join(", ")})" : ""
+        source_samples = sources_by_target[path]
 
         issues.add(
           code: :low_dofollow_inlinks,
           severity: :warning,
           category: :links,
           url: target_url,
-          message: "dofollow inbound links #{dofollow_count} below #{MIN_DOFOLLOW_INBOUND_LINKS}#{source_info}",
+          message: "incoming internal links without nofollow: #{dofollow_count}; minimum #{MIN_DOFOLLOW_INBOUND_LINKS}",
           details: {dofollow_inbound_count: dofollow_count, minimum: MIN_DOFOLLOW_INBOUND_LINKS, source_urls: source_samples}
         )
       end
@@ -507,8 +499,8 @@ module Crawlscope
           severity: :warning,
           category: :links,
           url: target_url,
-          message: "page has nofollow incoming internal links only",
-          details: {nofollow_inbound_count: nofollow_count, source_urls: nofollow_sources.first(MAX_SOURCES_IN_ERROR)}
+          message: "all incoming internal links use nofollow",
+          details: {nofollow_inbound_count: nofollow_count, source_urls: nofollow_sources}
         )
       end
 
@@ -524,15 +516,17 @@ module Crawlscope
           details: {
             dofollow_inbound_count: dofollow_count,
             nofollow_inbound_count: nofollow_count,
-            dofollow_source_urls: dofollow_sources.first(MAX_SOURCES_IN_ERROR),
-            nofollow_source_urls: nofollow_sources.first(MAX_SOURCES_IN_ERROR)
+            dofollow_source_urls: dofollow_sources,
+            nofollow_source_urls: nofollow_sources
           }
         )
       end
 
       def validate_canonical_targets(urls, pages, resolved_links, issues)
         sitemap_urls = urls.map { |url| Url.normalize(url, base_url: @base_url) }.compact
-        sitemap_pages = pages.select { |page| page.html? && sitemap_urls.include?(page.normalized_url) }
+        sitemap_pages = pages.select do |page|
+          page.html? && sitemap_urls.include?(page.normalized_url) && page.normalized_url.to_s == page.normalized_final_url.to_s
+        end
         return if sitemap_pages.size < 2
 
         dofollow_counts_by_path = dofollow_counts_by_final_path(resolved_links)
@@ -549,7 +543,7 @@ module Crawlscope
               severity: :warning,
               category: :links,
               url: canonical_url,
-              message: "canonical URL has no incoming internal links",
+              message: "canonical URL has no incoming internal links without nofollow",
               details: {source_url: page.url}
             )
           end
@@ -609,7 +603,7 @@ module Crawlscope
             severity: :warning,
             category: :metadata,
             url: page.url,
-            message: "canonical points to redirect",
+            message: "canonical #{canonical_url} redirects to #{target.final_url}",
             details: {canonical: canonical_url, final_url: target.final_url, status: target.status}
           )
         elsif !target.allowed?(@allowed_statuses)
@@ -618,7 +612,7 @@ module Crawlscope
             severity: :warning,
             category: :metadata,
             url: page.url,
-            message: "canonical points to HTTP #{target.status}",
+            message: "canonical #{canonical_url} returns HTTP #{target.status}",
             details: {canonical: canonical_url, status: target.status}
           )
         end

data/lib/crawlscope/rules/metadata.rb

@@ -21,7 +21,7 @@ module Crawlscope
         sitemap_urls = normalized_sitemap_urls(urls)
 
         pages.each do |page|
-          next unless page.html?
+          next unless page.html? && page.normalized_url.to_s == page.normalized_final_url.to_s
 
           validate_h1(page, issues)
           validate_title(page, issues)
@@ -47,7 +47,7 @@ module Crawlscope
             severity: :warning,
             category: :metadata,
             url: page.url,
-            message: "empty <h1>",
+            message: "empty <h1> tags: #{empty_h1s.size}",
             details: {count: empty_h1s.size}
           )
         end
@@ -93,7 +93,7 @@ module Crawlscope
         if title.empty?
           issues.add(code: :missing_title, severity: :warning, category: :metadata, url: page.url, message: "missing <title>", details: {})
         elsif title.length > TITLE_MAX_LENGTH
-          issues.add(code: :title_too_long, severity: :warning, category: :metadata, url: page.url, message: "title too long (#{title.length})", details: {length: title.length})
+          issues.add(code: :title_too_long, severity: :warning, category: :metadata, url: page.url, message: "title: #{title.length} characters; maximum #{TITLE_MAX_LENGTH}", details: {length: title.length})
         elsif repeated_site_name?(title)
           issues.add(code: :title_repeats_site_name, severity: :warning, category: :metadata, url: page.url, message: "title repeats #{@site_name}", details: {site_name: @site_name})
         end
@@ -117,9 +117,9 @@ module Crawlscope
         if description.empty?
           issues.add(code: :missing_meta_description, severity: :warning, category: :metadata, url: page.url, message: "missing meta description", details: {})
         elsif description.length < DESCRIPTION_MIN_LENGTH
-          issues.add(code: :meta_description_too_short, severity: :warning, category: :metadata, url: page.url, message: "meta description too short (#{description.length})", details: {length: description.length, minimum: DESCRIPTION_MIN_LENGTH})
+          issues.add(code: :meta_description_too_short, severity: :warning, category: :metadata, url: page.url, message: "meta description: #{description.length} characters; minimum #{DESCRIPTION_MIN_LENGTH}", details: {length: description.length, minimum: DESCRIPTION_MIN_LENGTH})
         elsif description.length > DESCRIPTION_MAX_LENGTH
-          issues.add(code: :meta_description_too_long, severity: :warning, category: :metadata, url: page.url, message: "meta description too long (#{description.length})", details: {length: description.length})
+          issues.add(code: :meta_description_too_long, severity: :warning, category: :metadata, url: page.url, message: "meta description: #{description.length} characters; maximum #{DESCRIPTION_MAX_LENGTH}", details: {length: description.length})
         end
       end
 
@@ -136,25 +136,25 @@ module Crawlscope
         return if canonical_matches_page?(normalized_canonical, normalized_page_url)
 
         details = {canonical: canonical}
-        issues.add(
-          code: :canonical_mismatch,
-          severity: :warning,
-          category: :metadata,
-          url: page.url,
-          message: "canonical mismatch (#{canonical})",
-          details: details
-        )
-
-        return unless sitemap_urls.include?(normalized_page_url)
-
-        issues.add(
-          code: :non_canonical_page_in_sitemap,
-          severity: :warning,
-          category: :sitemaps,
-          url: page.url,
-          message: "non-canonical page is included in sitemap",
-          details: details
-        )
+        if sitemap_urls.include?(normalized_page_url)
+          issues.add(
+            code: :non_canonical_page_in_sitemap,
+            severity: :warning,
+            category: :sitemaps,
+            url: page.url,
+            message: "sitemap lists this URL, but its canonical points to #{canonical}",
+            details: details
+          )
+        else
+          issues.add(
+            code: :canonical_mismatch,
+            severity: :warning,
+            category: :metadata,
+            url: page.url,
+            message: "canonical points to a different URL: #{canonical}",
+            details: details
+          )
+        end
       end
 
       def repeated_site_name?(title)
@@ -174,7 +174,7 @@ module Crawlscope
           severity: :warning,
           category: :metadata,
           url: page.url,
-          message: "Open Graph tags incomplete (missing #{missing.join(", ")})",
+          message: "missing Open Graph tags: #{missing.join(", ")}",
           details: {missing: missing}
         )
       end

data/lib/crawlscope/rules/structured_data.rb

@@ -49,7 +49,7 @@ module Crawlscope
               severity: :warning,
               category: :structured_data,
               url: page.url,
-              message: "#{source} parse error: #{data[:message]}",
+              message: "#{source_label(source)} parse error: #{data[:message]}",
               details: {source: source}
             )
             next
@@ -65,7 +65,7 @@ module Crawlscope
             severity: :warning,
             category: :structured_data,
             url: page.url,
-            message: "#{source} schema errors: #{errors.to_json}",
+            message: schema_error_message(source, errors),
             details: {errors: errors, source: source}
           )
         end
@@ -73,6 +73,15 @@ module Crawlscope
         validate_job_posting_count(page, items, issues)
       end
 
+      def source_label(source)
+        (source == "json-ld") ? "JSON-LD" : source
+      end
+
+      def schema_error_message(source, errors)
+        messages = errors.map { |error| Crawlscope::StructuredData::ErrorFormatter.format(error) }
+        "#{source_label(source)} #{messages.join("; ")}"
+      end
+
       def validate_job_posting_count(page, items, issues)
         job_postings = items.select { |item| structured_data_types(item.data).include?("JobPosting") }
         return if job_postings.size == 1
@@ -83,7 +92,7 @@ module Crawlscope
             severity: :warning,
             category: :structured_data,
             url: page.url,
-            message: "multiple JobPosting structured data blocks found",
+            message: "JobPosting blocks: #{job_postings.size}; expected 1",
             details: {count: job_postings.size}
           )
         elsif career_detail_page?(page.url)
@@ -107,7 +116,7 @@ module Crawlscope
           severity: :warning,
           category: :structured_data,
           url: page.url,
-          message: "#{source} structured data missing @type",
+          message: "#{source_label(source)} structured data missing @type",
           details: {paths: missing_paths, source: source}
         )
       end