abqari 1.1.0

data/lib/abqari/audit/links.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Abqari
+  class Audit
+    # Broken internal-link / missing-asset detector. Walks every `href`,
+    # `src`, and `srcset` in rendered HTML and flags any same-origin
+    # reference that doesn't resolve to a file we actually emitted.
+    # External (`http(s)://` to another host) references are skipped
+    # here — Privacy covers them — as are anchors / mailto / tel / data.
+    class Links < Rule
+      def run
+        output_paths = build_output_path_set
+        site_host    = host_for(@site.config['url'])
+
+        html_files.each do |file|
+          url  = page_url(file)
+          html = File.read(file, encoding: 'UTF-8')
+
+          # Strip `<pre>…</pre>` and inline `<code>…</code>` blocks
+          # before scanning. Rouge's HTML-lexer highlighting of an
+          # ERB or HTML example wraps the attribute value in
+          # `<span class="s">...</span>`, which a naive `href="…"`
+          # regex picks up as a "broken link" pointing at
+          # `</span><span class=` and similar fragments. Code
+          # samples aren't navigation — skip them.
+          scan_html = html.gsub(%r{<pre\b[^>]*>.*?</pre>}m, '')
+                          .gsub(%r{<code\b[^>]*>.*?</code>}m, '')
+
+          references(scan_html).each do |link|
+            next if link.empty?
+            next if link.start_with?('mailto:', 'tel:', 'data:', 'javascript:', '#')
+
+            # Same-origin absolute URLs (`https://mysite/gone/`) are
+            # checked like internal links; only cross-host ones are
+            # skipped (Privacy covers those). Previously BOTH branches
+            # fell through, so a broken absolute link to your own domain
+            # was invisible to every rule.
+            if link.start_with?('http://', 'https://')
+              link_host = host_for(link)
+              next unless site_host && link_host == site_host
+
+              link = (URI(link).path.to_s.empty? ? '/' : URI(link).path)
+            end
+
+            target = resolve_target(link, url)
+            next if output_paths.include?(target) ||
+                    output_paths.include?("#{target}index.html")
+
+            add(category: 'links', severity: 'error', location: url,
+                message: "Broken link/asset: #{link}")
+          end
+        end
+      end
+
+      private
+
+      # Every same-origin reference in the page: `href`, `src`, and each
+      # candidate URL inside a `srcset` (comma-separated `url descriptor`
+      # pairs). Query strings and fragments are trimmed off.
+      def references(html)
+        found = []
+        html.scan(/(?:href|src)="([^"#?]+)/) { |(l)| found << l }
+        html.scan(/srcset="([^"]+)"/) do |(set)|
+          set.split(',').each do |candidate|
+            u = candidate.strip.split(/\s+/).first.to_s.split(/[#?]/).first
+            found << u unless u.to_s.empty?
+          end
+        end
+        found
+      end
+
+      # Resolve a link to a root-relative path, honouring the browser's
+      # base-URL rules and collapsing `.`/`..` segments.
+      #
+      # The base for a RELATIVE link is the current page's directory. For
+      # a directory-style URL (`/posts/foo/`) that IS the URL itself —
+      # `File.dirname` would wrongly drop `foo/` and resolve bundle
+      # assets against `/posts/`, producing false "broken link" reports
+      # for the engine's own primary asset pattern.
+      def resolve_target(link, current_page_url)
+        raw = if link.start_with?('/')
+                link
+              else
+                base = current_page_url.end_with?('/') ? current_page_url : "#{File.dirname(current_page_url)}/"
+                "#{base}#{link}"
+              end
+        normalize_path(raw)
+      end
+
+      def normalize_path(path)
+        trailing = path.end_with?('/')
+        segments = []
+        path.split('/').each do |seg|
+          next if seg.empty? || seg == '.'
+
+          seg == '..' ? segments.pop : segments << seg
+        end
+        result = "/#{segments.join('/')}"
+        result += '/' if trailing && result != '/'
+        result
+      end
+
+      def build_output_path_set
+        paths = Set.new
+        # No `.sort` — populating a Set is order-invariant; the audit
+        # only does membership checks against `paths`, never iterates.
+        Dir.glob(File.join(@site.output_dir, '**', '*'), File::FNM_DOTMATCH).each do |entry|
+          next if File.directory?(entry)
+
+          rel = entry.sub(@site.output_dir, '')
+          paths << rel
+          paths << rel.sub(%r{/index\.html\z}, '/') if rel.end_with?('/index.html')
+        end
+        paths
+      end
+    end
+  end
+end

data/lib/abqari/audit/performance.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Abqari
+  class Audit
+    # Performance rule. Flags pages whose total image payload would
+    # punish a mobile visitor — the most common cause of bad Lighthouse
+    # scores on otherwise-clean static sites.
+    #
+    # Two thresholds, both per-page:
+    #   - Total image bytes on a page (the page's complete image
+    #     payload across all `<img>` and `<picture><source>` URLs
+    #     pointing at same-origin paths). Warn over 1 MB, error over
+    #     3 MB.
+    #   - Single-image bytes. A 5 MB hero in an otherwise-light page
+    #     defeats the whole pipeline. Warn at 500 KB, error at 1 MB.
+    #
+    # Skip pages with no images entirely. Redirect stubs are skipped.
+    class Performance < Rule
+      PAGE_TOTAL_WARN  = 1_000_000  # 1 MB
+      PAGE_TOTAL_ERROR = 3_000_000  # 3 MB
+      SINGLE_WARN      = 500_000    # 500 KB
+      SINGLE_ERROR     = 1_000_000  # 1 MB
+
+      def run
+        html_files.each do |file|
+          html = File.read(file, encoding: 'UTF-8')
+          next if html =~ /<meta\s+http-equiv=["']refresh/i
+
+          url = page_url(file)
+          image_paths = extract_image_urls(html)
+          next if image_paths.empty?
+
+          sizes = image_paths.filter_map { |path| size_for(path) }
+          flag_heavy_singles(url, sizes)
+          flag_heavy_page_total(url, sizes)
+        end
+      end
+
+      private
+
+      # Pull every `src="…"` and `srcset="…, …, …"` reference that
+      # looks like a same-origin image path (`/...` or relative). We
+      # only stat same-origin assets — external CDN images aren't
+      # something the audit can size locally.
+      def extract_image_urls(html)
+        urls = []
+
+        html.scan(/<img\s+[^>]*?src="([^"]+)"/i) { urls << ::Regexp.last_match(1) }
+        html.scan(/<source\s+[^>]*?srcset="([^"]+)"/i) do |srcset,|
+          srcset[0].to_s.split(',').each do |entry|
+            url, = entry.strip.split(/\s+/, 2)
+            urls << url if url
+          end
+        end
+
+        urls.uniq.reject { |u| u.empty? || u.start_with?('http://', 'https://', 'data:', '#') }
+      end
+
+      def size_for(url)
+        path = File.join(@site.output_dir, url.sub(%r{\A/}, ''))
+        return nil unless File.exist?(path) && File.file?(path)
+
+        [url, File.size(path)]
+      end
+
+      def flag_heavy_singles(page_url, sizes)
+        sizes.each do |url, bytes|
+          severity = if bytes >= SINGLE_ERROR    then 'error'
+                     elsif bytes >= SINGLE_WARN  then 'warn'
+                     end
+          next unless severity
+
+          add(category: 'perf', severity: severity, location: page_url,
+              message: "Image #{url} is #{format_kb(bytes)} (over the #{severity == 'error' ? '1 MB' : '500 KB'} threshold)",
+              suggestion: "Enable `images.optimise: true` in config/site.yml and rebuild, " \
+                          "or pre-compress this asset. AVIF at quality 50 typically saves 60–80% on photos.")
+        end
+      end
+
+      def flag_heavy_page_total(page_url, sizes)
+        # Sum the smallest variant per logical image — a `<picture>`
+        # block typically lists multiple widths for the same image
+        # under different filenames, but a visitor only fetches one
+        # per breakpoint. Take the smallest per basename as a fair
+        # proxy for "what the visitor actually downloads".
+        per_basename = sizes.group_by { |url, _| basename_key(url) }
+        effective = per_basename.values.map { |group| group.map { |_, b| b }.min || 0 }
+        total = effective.sum
+
+        severity = if total >= PAGE_TOTAL_ERROR  then 'error'
+                   elsif total >= PAGE_TOTAL_WARN then 'warn'
+                   end
+        return unless severity
+
+        threshold = severity == 'error' ? '3 MB' : '1 MB'
+        add(category: 'perf', severity: severity, location: page_url,
+            message: "Total image weight on this page is #{format_kb(total)} (over #{threshold})",
+            suggestion: 'Reduce hero/figure count, or compress further. Consider lazy-loading below-fold images via `loading="lazy"` (already default on auto-optimised images).')
+      end
+
+      def basename_key(url)
+        # Strip the `-<width>.<hash>` fingerprint suffix so variants of
+        # the same source coalesce: hero-1200.abc123.jpg → hero.jpg
+        # and hero-800.def456.avif → hero.avif both bucket under their
+        # base filename.
+        bn = File.basename(url)
+        ext = File.extname(bn)
+        bn.sub(/-\d+\.[0-9a-f]+#{Regexp.escape(ext)}\z/, ext)
+      end
+
+      def format_kb(bytes)
+        if bytes >= 1_000_000
+          format('%.1f MB', bytes / 1_000_000.0)
+        else
+          format('%d KB', bytes / 1_000.0)
+        end
+      end
+    end
+  end
+end

data/lib/abqari/audit/privacy.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module Abqari
+  class Audit
+    # Privacy rule. Surfaces every cross-origin resource referenced from
+    # rendered HTML (`src`/`href` to a host other than the site's own).
+    # Info-severity because external loads are a deliberate choice, not
+    # always a bug — but each one is a third-party tracking vector worth
+    # auditing.
+    #
+    # No-ops when `config.url` isn't set (we can't tell what "external"
+    # means without knowing what's internal).
+    class Privacy < Rule
+      def run
+        site_host = host_for(@site.config['url'])
+        return unless site_host
+
+        seen = Set.new
+
+        html_files.each do |file|
+          url  = page_url(file)
+          html = File.read(file, encoding: 'UTF-8')
+
+          html.scan(%r{(?:src|href)="(https?://[^"]+)"}).each do |(external_url)|
+            ext_host = host_for(external_url)
+            next if ext_host.nil? || ext_host == site_host
+
+            key = "#{url}|#{external_url}"
+            next if seen.include?(key)
+
+            seen << key
+            add(category: 'privacy', severity: 'info', location: url,
+                message: "External resource loaded: #{external_url}",
+                suggestion: 'Consider self-hosting to avoid third-party tracking')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abqari/audit/rule.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Abqari
+  class Audit
+    # Base class for audit rules. Each rule lives in its own file under
+    # `lib/abqari/audit/<category>.rb`, inherits from this, and implements
+    # `#run`. Shared helpers (`html_files`, `page_url`, `add`) live here
+    # so individual rules stay focused on their domain logic.
+    #
+    # Rules are stateless across runs — instantiated by Audit#run with
+    # the current site and findings list, then discarded. Caching that
+    # makes sense for the duration of a single audit (e.g. memoised
+    # `html_files`) lives on the instance.
+    class Rule
+      def initialize(site, findings)
+        @site = site
+        @findings = findings
+      end
+
+      # Subclasses override. The default raises so a half-finished rule
+      # surfaces immediately in tests instead of silently no-opping.
+      def run
+        raise NotImplementedError, "#{self.class.name} must implement #run"
+      end
+
+      protected
+
+      def add(category:, severity:, location:, message:, suggestion: nil)
+        @findings << {
+          category: category,
+          severity: severity,
+          location: location,
+          message: message,
+          suggestion: suggestion
+        }
+      end
+
+      # Every rendered HTML file in the build output, sorted for stable
+      # iteration. Memoised per rule instance (one audit run = one glob
+      # per category, which is cheaper than chasing global state).
+      def html_files
+        @html_files ||= Dir.glob(File.join(@site.output_dir, '**', '*.html')).sort
+      end
+
+      def page_url(file)
+        file.sub(@site.output_dir, '').sub(%r{/index\.html\z}, '/')
+      end
+
+      def host_for(url)
+        URI(url).host
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/lib/abqari/audit/seo.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Abqari
+  class Audit
+    # SEO rule. Catches:
+    #   - Missing meta descriptions
+    #   - Title / description length problems
+    #   - Duplicate titles across pages
+    #   - Missing og:image (info — no social-share preview)
+    #   - Workshops without Event JSON-LD
+    #   - Publications without Book JSON-LD
+    #
+    # Redirect stubs (meta-refresh-only pages) are skipped — they're
+    # not user-facing content, so SEO rules don't apply.
+    class SEO < Rule
+      TITLE_MAX_CHARS = 60
+      DESC_MAX_CHARS  = 160
+
+      def run
+        titles = {}
+
+        html_files.each do |file|
+          url  = page_url(file)
+          html = File.read(file, encoding: 'UTF-8')
+          next if html.include?('http-equiv="refresh"')
+
+          check_title(html, url, titles)
+          check_description(html, url)
+          check_og_image(html, url)
+          check_workshop_event_jsonld(html, url)
+          check_publication_book_jsonld(html, url)
+        end
+
+        flag_duplicate_titles(titles)
+      end
+
+      private
+
+      def check_title(html, url, titles)
+        title = html[%r{<title>(.*?)</title>}m, 1]
+        return unless title
+
+        (titles[title] ||= []) << url
+        return unless title.length > TITLE_MAX_CHARS
+
+        add(category: 'seo', severity: 'warn', location: url,
+            message: "Title is #{title.length} chars",
+            suggestion: "Aim for #{TITLE_MAX_CHARS} or fewer for search snippets")
+      end
+
+      def check_description(html, url)
+        desc = html[/<meta name="description" content="([^"]*)"/, 1]
+
+        if desc.nil? || desc.empty?
+          add(category: 'seo', severity: 'warn', location: url,
+              message: 'Missing meta description')
+        elsif desc.length > DESC_MAX_CHARS
+          add(category: 'seo', severity: 'warn', location: url,
+              message: "Description is #{desc.length} chars",
+              suggestion: "Aim for #{DESC_MAX_CHARS} or fewer")
+        end
+      end
+
+      def check_og_image(html, url)
+        og_image = html[/<meta property="og:image" content="[^"]*"/]
+        return if og_image
+
+        add(category: 'seo', severity: 'info', location: url,
+            message: 'Missing og:image (no social-share preview)',
+            suggestion: 'Set `image:` in frontmatter, or a site-wide `share_image:` in config')
+      end
+
+      def check_workshop_event_jsonld(html, url)
+        return unless url.start_with?('/workshops/') && url != '/workshops/'
+        return if url.include?('/page/')
+        return if html.match?(/"@type"\s*:\s*"Event"/)
+
+        add(category: 'seo', severity: 'warn', location: url,
+            message: 'Workshop has no Event JSON-LD',
+            suggestion: 'Workshop frontmatter needs `date_from:` (and ideally `date_to:`, `location:`, `price:`) for the Event partial to render')
+      end
+
+      def check_publication_book_jsonld(html, url)
+        return unless url.start_with?('/publications/', '/books/')
+        return if url.match?(%r{\A/(publications|books)/\z})
+        return if url.include?('/page/')
+        return if html.match?(/"@type"\s*:\s*"Book"/)
+
+        add(category: 'seo', severity: 'warn', location: url,
+            message: 'Publication has no Book JSON-LD',
+            suggestion: 'Check that `_book_jsonld` is rendered from the publication layout and the page has a title')
+      end
+
+      def flag_duplicate_titles(titles)
+        titles.each do |title, urls|
+          next if urls.size <= 1
+
+          add(category: 'seo', severity: 'warn',
+              location: urls.join(', '),
+              message: "Duplicate title: \"#{title}\"")
+        end
+      end
+    end
+  end
+end

data/lib/abqari/audit.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'uri'
+require 'time'
+
+require_relative 'audit/rule'
+require_relative 'audit/links'
+require_relative 'audit/seo'
+require_relative 'audit/a11y'
+require_relative 'audit/privacy'
+require_relative 'audit/performance'
+require_relative 'audit/dependencies'
+require_relative 'audit/content'
+
+module Abqari
+  # Site audit orchestrator. Each check lives in its own rule class
+  # under `lib/abqari/audit/`; this file is responsible for:
+  #
+  #   - Rebuilding the site (so the audit reads fresh _site/ output).
+  #   - Invoking every rule in `RULES` against shared findings list.
+  #   - Writing the markdown report at `<site>/audit/<timestamp>.md`.
+  #   - Exposing `findings` + `count(at_least:)` so `bin/audit --strict`
+  #     can gate CI on severity.
+  #
+  # The split keeps the orchestrator under ~100 lines and lets each
+  # rule grow independently. Adding a new category is: add a file
+  # under audit/, add the class to RULES, add the category label to
+  # CATEGORIES.
+  class Audit
+    SEVERITIES = %w[error warn info].freeze
+    CATEGORIES = {
+      'links'   => 'Links',
+      'seo'     => 'SEO',
+      'a11y'    => 'Accessibility',
+      'privacy' => 'Privacy',
+      'perf'    => 'Performance',
+      'deps'    => 'Dependencies',
+      'content' => 'Content'
+    }.freeze
+
+    # Rule classes, in execution order. Order matters only for the
+    # output report — findings are grouped by category, not insertion
+    # order — but Links first keeps the report scan-friendly: errors
+    # appear before warnings.
+    RULES = [Links, SEO, A11y, Privacy, Performance, Dependencies, Content].freeze
+
+    attr_reader :findings
+
+    def initialize(site)
+      @site = site
+      @findings = []
+    end
+
+    def run
+      # No syndication / webmention sending during an audit — auditing a
+      # not-yet-deployed post must not broadcast it. See Site#build.
+      @site.build(side_effects: false)
+      RULES.each { |klass| klass.new(@site, @findings).run }
+      write_report
+      self
+    end
+
+    # Count findings at or above the given severity. Used by `bin/audit
+    # --strict` to set the process exit code.
+    def count(at_least: 'error')
+      threshold = SEVERITIES.index(at_least.to_s) or
+        raise ArgumentError, "unknown severity #{at_least.inspect}, expected one of #{SEVERITIES.inspect}"
+      @findings.count { |f| (SEVERITIES.index(f[:severity]) || SEVERITIES.size) <= threshold }
+    end
+
+    private
+
+    def write_report
+      # Audit reports live in the consuming site's repo so they can be
+      # committed alongside the content they audit.
+      audit_dir = File.join(@site.site_root, 'audit')
+      FileUtils.mkdir_p(audit_dir)
+      filename = Time.now.strftime('%Y-%m-%d-%H%M.md')
+      File.write(File.join(audit_dir, filename), build_report)
+
+      counts = @findings.group_by { |f| f[:severity] }.transform_values(&:size)
+      summary = SEVERITIES.map { |s| "#{counts[s] || 0} #{s}" }.join(', ')
+      Log.info "Audit complete: audit/#{filename} (#{summary})"
+    end
+
+    def build_report
+      lines = [
+        '# Abqari site audit', '',
+        "Generated: #{Time.now.iso8601}",
+        "Environment: #{@site.env}", ''
+      ]
+      lines.concat(summary_table)
+      lines << ''
+      lines.concat(suggested_fixes_section)
+
+      CATEGORIES.each do |key, name|
+        category_findings = @findings.select { |f| f[:category] == key }
+        next if category_findings.empty?
+
+        lines << "## #{name}"
+        lines << ''
+        category_findings.each do |f|
+          lines << "- **[#{f[:severity]}]** `#{f[:location]}` — #{f[:message]}"
+          lines << "  - #{f[:suggestion]}" if f[:suggestion]
+        end
+        lines << ''
+      end
+
+      lines << '## All clear' if @findings.empty?
+      "#{lines.join("\n")}\n"
+    end
+
+    def summary_table
+      counts = @findings.group_by { |f| f[:category] }
+                       .transform_values { |fs| fs.group_by { |f| f[:severity] }.transform_values(&:size) }
+
+      lines = ['## Summary', '']
+      lines << '| Category | Errors | Warnings | Info |'
+      lines << '| --- | --- | --- | --- |'
+      CATEGORIES.each do |key, name|
+        c = counts[key] || {}
+        lines << "| #{name} | #{c['error'] || 0} | #{c['warn'] || 0} | #{c['info'] || 0} |"
+      end
+      lines
+    end
+
+    # Surface `bundle update <gem>` commands from dependency findings at
+    # the top of the report. Dependabot-adjacent: tells the reader the
+    # exact commands to run before they scroll through advisories.
+    def suggested_fixes_section
+      commands = @findings
+                 .select { |f| f[:category] == 'deps' && f[:suggestion]&.include?('bundle update') }
+                 .map { |f| f[:suggestion][/`bundle update[^`]+`/, 0] }
+                 .compact
+                 .uniq
+      return [] if commands.empty?
+
+      [
+        '## Suggested fixes', '',
+        'Run these commands to resolve the dependency findings below:', '',
+        '```bash',
+        *commands.map { |c| c.delete('`') },
+        '```', '',
+        'Then re-run `bin/audit` to confirm.', ''
+      ]
+    end
+  end
+end