abqari 1.1.0

data/lib/abqari/asset_pipeline.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+
+module Abqari
+  class AssetPipeline
+    OUTPUT_SUBDIR = 'assets'
+    HASH_LENGTH = 10
+    BUNDLE_LOGICAL = 'css/bundle.css'
+    # A theme name is a directory name under themes/ and nothing more.
+    # The strict pattern is load-bearing: the name is joined into
+    # filesystem paths in several places (here, ArtifactWriter,
+    # Renderer), so without it `theme: ../something` walks and
+    # publishes arbitrary directories. Same containment class the
+    # symlink guards enforce.
+    THEME_NAME_RE = /\A[a-z0-9_-]+\z/.freeze
+    # Extensions that get minified before fingerprinting (production
+    # only — dev keeps sources readable for devtools).
+    MINIFY_KINDS = { '.css' => :css, '.js' => :js }.freeze
+    # Themes that bring their own structural CSS. Mirror of the
+    # `_head.html.erb` conditional that skips `_common.css`.
+    NO_COMMON_THEMES = %w[bootstrap none].freeze
+
+    def initialize(site)
+      @site = site
+      @paths = {}
+      @sources = {}
+    end
+
+    def process
+      validate_theme!
+
+      # Processing order matters — later passes overwrite earlier ones
+      # on logical-path conflict (same filename).
+      #
+      # Within a category (theme vs app/assets), engine first, site
+      # second — so a site can override a theme file or a structural
+      # CSS asset just by dropping its own version at the same path.
+      #
+      # Between categories, themes lose to app/assets (preserving the
+      # original semantic: `_common.css` and `site.css` win over
+      # theme-bundled CSS on conflict). Hence the order:
+      #   1. engine theme   →  2. site theme
+      #   3. engine assets  →  4. site assets
+      #
+      # A theme's `public/` subtree is NOT an asset source — it's the
+      # verbatim passthrough tree ArtifactWriter#copy_public ships to
+      # the site root (e.g. the vendored Bootstrap dist). Walking it
+      # here used to fingerprint ~700 KB of dead, unreferenced copies
+      # into `_site/assets/public/`.
+      [engine_theme_dir, site_theme_dir].uniq.each do |dir|
+        process_dir(dir, skip_public: true) if dir && Dir.exist?(dir)
+      end
+      [engine_app_assets, site_app_assets].uniq.each do |dir|
+        process_dir(dir) if dir && Dir.exist?(dir)
+      end
+      build_css_bundle
+    end
+
+    def path_for(name)
+      @paths[name] || raise(ArgumentError, "Unknown asset: #{name}. Add it to app/assets/ or themes/#{theme_name}/.")
+    end
+
+    def theme_name
+      @site.config['theme'] || SiteConfig::DEFAULTS['theme']
+    end
+
+    # Fail fast — called at the top of Site#build, BEFORE the output
+    # dir is wiped, so a config typo aborts with one clear message
+    # instead of N per-page "Unknown asset: css/app.css" failures (or,
+    # for a traversal-shaped name, a walk of whatever the path
+    # resolves to).
+    def validate_theme!
+      name = theme_name.to_s
+      return if name == 'none'
+
+      unless name.match?(THEME_NAME_RE)
+        raise PathSafe::Error,
+              "invalid theme name #{name.inspect}: must match #{THEME_NAME_RE.inspect} " \
+              "(lowercase letters, digits, '-', '_'), or 'none'"
+      end
+
+      unless Dir.exist?(File.join(@site.engine_root, 'themes', name)) ||
+             Dir.exist?(File.join(@site.site_root, 'themes', name))
+        raise "unknown theme #{name.inspect} — no themes/#{name}/ in the site or the engine. " \
+              "Available: #{available_theme_names.join(', ')}, or 'none'"
+      end
+
+      return if theme_app_css_candidates.any? { |f| File.file?(f) }
+
+      raise "theme #{name.inspect} has no css/app.css — looked in " \
+            "themes/#{name}/css/ (site and engine) and app/assets/css/ (site). " \
+            'Every theme needs one, even if empty; it anchors the CSS bundle.'
+    end
+
+    private
+
+    def available_theme_names
+      names = Dir.children(File.join(@site.engine_root, 'themes')).sort
+      site_themes = File.join(@site.site_root, 'themes')
+      names |= Dir.children(site_themes).sort if Dir.exist?(site_themes)
+      names.select { |n| n.match?(THEME_NAME_RE) }
+    end
+
+    # Everywhere a theme's `css/app.css` may legitimately live, in
+    # override order. `app/assets/css/app.css` is the `theme: none`
+    # convention ("bring your own CSS"), but it satisfies any theme.
+    def theme_app_css_candidates
+      [
+        File.join(@site.site_root, 'app', 'assets', 'css', 'app.css'),
+        File.join(@site.site_root, 'themes', theme_name.to_s, 'css', 'app.css'),
+        File.join(@site.engine_root, 'themes', theme_name.to_s, 'css', 'app.css')
+      ]
+    end
+
+    def engine_app_assets
+      File.join(@site.engine_root, 'app', 'assets')
+    end
+
+    def site_app_assets
+      File.join(@site.site_root, 'app', 'assets')
+    end
+
+    def engine_theme_dir
+      return nil if theme_name.to_s == 'none'
+
+      File.join(@site.engine_root, 'themes', theme_name)
+    end
+
+    def site_theme_dir
+      return nil if theme_name.to_s == 'none'
+
+      File.join(@site.site_root, 'themes', theme_name)
+    end
+
+    def process_dir(src, skip_public: false)
+      Dir.glob(File.join(src, '**', '*')).sort.each do |entry|
+        next if File.directory?(entry)
+        next if File.basename(entry).start_with?('.')
+        next if skip_public && entry.start_with?(File.join(src, 'public') + File::SEPARATOR)
+        next if entry.include?(File.join('assets', 'images') + File::SEPARATOR)
+        # Symlink containment — same invariant `BundleAssets`,
+        # `ImagePipeline`, and `SiteLoader` enforce. A theme or
+        # `app/assets/` file that symlinks outside `site_root` (e.g.
+        # `app/assets/css/main.css` → `/etc/passwd`) is skipped with
+        # a warning rather than copied into `_site/`. Trust model
+        # still treats `app/assets/` as author-controlled, but
+        # consistency across walkers keeps future contributors from
+        # assuming any one of them is sufficient on its own.
+        next if @site.external_symlink?(entry)
+
+        logical = entry.sub("#{src}/", '')
+        write_asset(logical, processed_content(entry, logical))
+        @sources[logical] = entry
+      end
+    end
+
+    # Fingerprint + write one asset. The hash is computed over the
+    # content actually shipped (post-minification), so the name stays
+    # content-addressable: if the fingerprinted target already exists,
+    # its content matches and the write is skipped.
+    def write_asset(logical, content)
+      fingerprinted = fingerprint(logical, content)
+      dest = File.join(@site.output_dir, OUTPUT_SUBDIR, fingerprinted)
+
+      unless File.exist?(dest)
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.binwrite(dest, content)
+      end
+
+      @paths[logical] = "/#{OUTPUT_SUBDIR}/#{fingerprinted}"
+    end
+
+    def processed_content(entry, logical)
+      raw = File.binread(entry)
+      kind = MINIFY_KINDS[File.extname(logical)]
+      return raw unless kind && minify?
+
+      text = raw.dup.force_encoding('UTF-8')
+      return raw unless text.valid_encoding?
+
+      Minifier.public_send(kind, text)
+    end
+
+    # Concatenate the render-blocking stylesheets into ONE fingerprinted
+    # file, in the same cascade order as the individual <link> tags it
+    # replaces: syntax (Rouge theme), `_common.css`, theme `app.css`,
+    # `site.css` override. `_head.html.erb` links only the bundle when
+    # it exists; when it doesn't (a `none`-theme site without its own
+    # app.css, or a site shipping a literal `bundle.css` of its own),
+    # the partial falls back to the individual links so the behaviour
+    # and error surface are unchanged.
+    def build_css_bundle
+      return unless @sources['css/app.css']
+
+      if @sources[BUNDLE_LOGICAL]
+        Log.warn "app/assets/css/bundle.css shadows the generated CSS bundle — " \
+                 'falling back to individual stylesheet links.'
+        return
+      end
+
+      pieces = []
+      pieces << SyntaxHighlighter::Stylesheet.new(@site).css if @site.config['syntax_highlighting']
+      unless NO_COMMON_THEMES.include?(theme_name.to_s)
+        common = @sources['css/_common.css']
+        pieces << File.read(common, encoding: 'UTF-8') if common
+      end
+      pieces << File.read(@sources['css/app.css'], encoding: 'UTF-8')
+      site_css = @sources['css/site.css']
+      pieces << File.read(site_css, encoding: 'UTF-8') if site_css
+
+      content = pieces.join("\n")
+      content = Minifier.css(content) if minify?
+      write_asset(BUNDLE_LOGICAL, content)
+    end
+
+    # Assets ship minified whenever HTML does — one `minify:` switch
+    # governs the whole output. Same logic as Renderer#minify_html?
+    # (duplicated rather than delegated: the renderer memo may not
+    # exist yet when assets process).
+    def minify?
+      return @site.config['minify'] if @site.config.key?('minify')
+
+      @site.env == :production
+    end
+
+    def fingerprint(logical, content)
+      hash = Digest::SHA1.hexdigest(content)[0, HASH_LENGTH]
+      ext = File.extname(logical)
+      base = logical[0...-ext.length]
+      "#{base}.#{hash}#{ext}"
+    end
+  end
+end

data/lib/abqari/audit/a11y.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Abqari
+  class Audit
+    # Accessibility rule. Catches structural issues that hurt
+    # screen-reader / keyboard users:
+    #   - <img> elements without alt attribute (error)
+    #   - Multiple <h1> elements per page (warn)
+    #   - Missing skip-to-content link (warn)
+    #   - Missing <main id="main-content"> landmark (warn)
+    #   - Multiple <nav>s without aria-label (warn)
+    #
+    # Redirect-stub pages (meta-refresh) are skipped — they have no
+    # user-facing content, so landmark rules don't apply.
+    class A11y < Rule
+      def run
+        html_files.each do |file|
+          url  = page_url(file)
+          html = File.read(file, encoding: 'UTF-8')
+          next if html =~ /<meta\s+http-equiv=["']refresh/i
+
+          check_img_alt(html, url)
+          check_single_h1(html, url)
+          check_skip_link(html, url)
+          check_main_landmark(html, url)
+          check_nav_labels(html, url)
+        end
+      end
+
+      private
+
+      def check_img_alt(html, url)
+        html.scan(/<img\s+([^>]+?)>/).each do |(attrs)|
+          next if attrs =~ /\balt\s*=/
+
+          src = attrs[/src\s*=\s*"([^"]+)"/, 1] || '(unknown source)'
+          add(category: 'a11y', severity: 'error', location: url,
+              message: "Image without alt attribute: #{src}",
+              suggestion: 'Add alt="" for decorative images, descriptive alt for content')
+        end
+      end
+
+      def check_single_h1(html, url)
+        h1_count = html.scan(/<h1\b/).size
+        return unless h1_count > 1
+
+        add(category: 'a11y', severity: 'warn', location: url,
+            message: "#{h1_count} <h1> elements found",
+            suggestion: 'Use exactly one <h1> per page; nest others as <h2>+')
+      end
+
+      def check_skip_link(html, url)
+        return if html =~ /class="skip-link"|href="#main-content"/
+
+        add(category: 'a11y', severity: 'warn', location: url,
+            message: 'Missing skip-to-content link',
+            suggestion: "Add <%= render 'partials/skip_link' %> as the first thing in <body>")
+      end
+
+      def check_main_landmark(html, url)
+        return if html =~ /<main\b[^>]*\bid\s*=\s*"main-content"/
+
+        add(category: 'a11y', severity: 'warn', location: url,
+            message: 'Missing <main id="main-content"> landmark',
+            suggestion: 'Wrap primary content in <main id="main-content" tabindex="-1">')
+      end
+
+      def check_nav_labels(html, url)
+        unlabelled = html.scan(/<nav\b([^>]*)>/).reject do |(attrs)|
+          attrs =~ /\baria-label(?:ledby)?\s*=/
+        end
+        return unless unlabelled.size.positive? && html.scan(/<nav\b/).size > 1
+
+        add(category: 'a11y', severity: 'warn', location: url,
+            message: "#{unlabelled.size} <nav> element(s) without aria-label",
+            suggestion: 'Add aria-label="Primary" / "Pagination" / etc. to disambiguate')
+      end
+    end
+  end
+end

data/lib/abqari/audit/content.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Abqari
+  class Audit
+    # Content-quality rule:
+    #   - Posts without a frontmatter `description:` (warn)
+    #   - Tags used by only one post (info)
+    #   - Frontmatter values that fall outside an operator-supplied
+    #     whitelist (warn) — see `validate:` in config/site.yml
+    #   - `series_position:` problems that break prev/next navigation
+    #     silently (warn / info)
+    class Content < Rule
+      def run
+        flag_posts_without_description
+        flag_single_use_tags
+        check_frontmatter_whitelists
+        flag_series_position_problems
+      end
+
+      private
+
+      def flag_posts_without_description
+        @site.posts.each do |post|
+          next if post.frontmatter['description'].to_s.length.positive?
+
+          add(category: 'content', severity: 'warn', location: post.url,
+              message: 'Post has no description',
+              suggestion: 'Add a `description:` to front matter for OG/SEO')
+        end
+      end
+
+      def flag_single_use_tags
+        @site.posts_by_term('tags').each do |tag, posts|
+          next if posts.size > 1
+
+          add(category: 'content', severity: 'info', location: posts.first.url,
+              message: "Tag '#{tag}' is used by only one post",
+              suggestion: 'Consolidate with a related tag or remove')
+        end
+      end
+
+      # Frontmatter validation against operator-supplied whitelists.
+      # `validate:` in config/site.yml maps a frontmatter field to a
+      # YAML data file whose top-level keys are the allowed values:
+      #
+      #   validate:
+      #     country: data/countries.yml
+      #     language: data/languages.yml
+      #
+      # Catches typos before they ship as broken `/country/syra/` pages.
+      def check_frontmatter_whitelists
+        validate_cfg = @site.config['validate']
+        return unless validate_cfg.is_a?(Hash) && validate_cfg.any?
+
+        whitelists = load_whitelists(validate_cfg)
+        flag_unknown_values(whitelists)
+      end
+
+      def load_whitelists(validate_cfg)
+        whitelists = {}
+        validate_cfg.each do |field, path|
+          full = File.join(@site.site_root, path.to_s)
+          next unless File.exist?(full)
+
+          data = YAML.safe_load_file(full, permitted_classes: Abqari::YAML_PERMITTED_CLASSES) || {}
+          whitelists[field] = data.keys.map { |k| k.to_s.downcase } if data.is_a?(Hash)
+        end
+        whitelists
+      end
+
+      # Series ordering problems. All three findings here share a
+      # failure mode: the page still builds, still appears on its series
+      # index, and still looks correct in isolation — only the prev/next
+      # chain quietly loses it. Nothing else in the build surfaces that,
+      # which is what makes them worth an audit rule.
+      #
+      # `Site#series_sibling` requires an Integer position (a quoted
+      # YAML "3" is skipped) and compares strictly (two pages sharing a
+      # position are invisible to each other, so the chain skips one).
+      #
+      # Scoped per collection, matching how the series taxonomies and
+      # `series_sibling` scope: a lesson and a post with the same
+      # `series:` value are independent series, not one shared run.
+      def flag_series_position_problems
+        pages_in_series.group_by { |page| [page.collection, page.frontmatter['series'].to_s] }
+                       .each { |(_collection, series), pages| check_series_positions(series, pages) }
+      end
+
+      def pages_in_series
+        @site.all_pages.select do |page|
+          next false unless page.respond_to?(:collection) && page.collection
+          next false unless page.respond_to?(:frontmatter) && page.frontmatter.is_a?(Hash)
+
+          !page.frontmatter['series'].to_s.strip.empty?
+        end
+      end
+
+      def check_series_positions(series, pages)
+        by_position = {}
+
+        pages.each do |page|
+          position = page.frontmatter['series_position']
+
+          if position.nil?
+            add(category: 'content', severity: 'info', location: page.url,
+                message: "In series '#{series}' but has no series_position",
+                suggestion: 'Add an Integer `series_position:` so prev/next navigation can order it')
+          elsif !position.is_a?(Integer)
+            add(category: 'content', severity: 'warn', location: page.url,
+                message: "series_position #{position.inspect} is a #{position.class}, not an Integer",
+                suggestion: 'Unquote the value — a non-Integer position is skipped by prev/next navigation')
+          else
+            (by_position[position] ||= []) << page
+          end
+        end
+
+        flag_duplicate_positions(series, by_position)
+      end
+
+      def flag_duplicate_positions(series, by_position)
+        by_position.each do |position, sharers|
+          next if sharers.size < 2
+
+          others = sharers.size - 1
+          sharers.each do |page|
+            add(category: 'content', severity: 'warn', location: page.url,
+                message: "series_position #{position} in '#{series}' is shared with " \
+                         "#{others} other #{others == 1 ? 'page' : 'pages'}",
+                suggestion: 'Give each page a distinct position — duplicates make prev/next skip one')
+          end
+        end
+      end
+
+      def flag_unknown_values(whitelists)
+        @site.taxonomy_pages.each do |page|
+          whitelists.each do |field, allowed|
+            values = Array(page.frontmatter[field]).reject { |v| v.to_s.strip.empty? }
+            next if values.empty?
+
+            values.each do |value|
+              next if allowed.include?(value.to_s.downcase)
+
+              add(category: 'content', severity: 'warn', location: page.url,
+                  message: "Unrecognised #{field}: '#{value}'",
+                  suggestion: 'Add it to the whitelist file or check for a typo')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/abqari/audit/dependencies.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Abqari
+  class Audit
+    # Dependency rule. Two sub-checks:
+    #   - bundler-audit for known CVE advisories
+    #   - `bundle outdated` for behind-latest gems
+    #
+    # Both run inside `Dir.chdir(@site.site_root)` so they target the
+    # consuming site's Gemfile.lock when abqari is consumed as a gem.
+    class Dependencies < Rule
+      def run
+        Dir.chdir(@site.site_root) do
+          check_security_advisories
+          check_outdated_gems
+        end
+      end
+
+      private
+
+      # Parses bundler-audit per-finding blocks: gem name, version,
+      # advisory ID, criticality, title, recommended upgrade, ref URL.
+      # Emits one finding per advisory plus a one-liner that updates
+      # every vulnerable gem at once.
+      def check_security_advisories
+        unless command_available?('bundle-audit')
+          add(category: 'deps', severity: 'info', location: 'system',
+              message: 'CVE check skipped: bundler-audit not installed',
+              suggestion: '`gem install bundler-audit` then re-run audit')
+          return
+        end
+
+        output = `bundle-audit check --update 2>&1`
+        return if output.include?('No vulnerabilities')
+
+        vulnerable_gems = parse_bundler_audit_output(output)
+        return if vulnerable_gems.empty?
+
+        add(
+          category: 'deps',
+          severity: 'info',
+          location: 'Gemfile.lock',
+          message: "#{vulnerable_gems.uniq.size} gem(s) need security updates",
+          suggestion: "Run `bundle update #{vulnerable_gems.uniq.join(' ')}` to address all listed advisories"
+        )
+      end
+
+      def parse_bundler_audit_output(output)
+        vulnerable_gems = []
+
+        output.split(/\n\s*\n/).each do |block|
+          next unless block =~ /^\s*Name:/
+
+          fields = block.scan(/^\s*([A-Za-z]+):\s*(.+?)\s*$/).to_h
+          name = fields['Name']
+          next unless name
+
+          vulnerable_gems << name
+          emit_advisory_finding(name, fields)
+        end
+
+        vulnerable_gems
+      end
+
+      def emit_advisory_finding(name, fields)
+        advisory    = fields['GHSA'] || fields['CVE'] || 'unknown'
+        criticality = (fields['Criticality'] || 'unknown').downcase
+        version     = fields['Version']
+        title       = fields['Title']
+        solution    = fields['Solution']
+        url         = fields['URL']
+
+        message_parts = ["#{name} #{version}".rstrip, "(#{advisory})"]
+        message_parts << "[#{criticality}]" unless criticality == 'unknown'
+        message_parts << "— #{title}" if title
+
+        suggestion_parts = ["Run `bundle update #{name}`"]
+        suggestion_parts << solution.sub(/\Aupgrade to /, '(target: ').concat(')') if solution
+        suggestion_parts << url if url
+
+        add(
+          category: 'deps',
+          severity: cve_severity(criticality),
+          location: 'Gemfile.lock',
+          message: message_parts.join(' '),
+          suggestion: suggestion_parts.join(' · ')
+        )
+      end
+
+      # `--parseable` for stable cross-version output; falls back to the
+      # human-readable form so older Bundler still works.
+      def check_outdated_gems
+        output = `bundle outdated --strict --parseable 2>/dev/null`
+        output = `bundle outdated --strict 2>/dev/null` if output.empty?
+
+        output.lines.each do |line|
+          match = line.match(/(\S+)\s+\(newest\s+(\S+),\s+installed\s+(\S+)/) ||
+                  line.match(/^\s*\*\s+(\S+)\s+\(newest\s+(\S+),\s+installed\s+(\S+)/)
+          next unless match
+
+          name, newest, installed = match[1], match[2], match[3]
+          add(category: 'deps', severity: 'info', location: 'Gemfile',
+              message: "#{name} is outdated (installed #{installed}, latest #{newest})",
+              suggestion: "Run `bundle update #{name}` to upgrade")
+        end
+      end
+
+      def cve_severity(criticality)
+        case criticality
+        when 'critical', 'high' then 'error'
+        when 'medium'           then 'warn'
+        else                         'info'
+        end
+      end
+
+      # PATH walk instead of `system("command -v #{cmd} ...")` so the
+      # caller can't inadvertently introduce shell injection. Callers
+      # are hardcoded today, but the argv-free form is the safer default
+      # and matches Search#command_available?.
+      def command_available?(cmd)
+        ENV['PATH'].to_s.split(File::PATH_SEPARATOR).any? do |dir|
+          File.executable?(File.join(dir, cmd))
+        end
+      end
+    end
+  end
+end