abqari 1.1.0

data/lib/abqari/site_config.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Abqari
+  # Lightweight schema check for `config/site.yml`. The goal is not full
+  # schema validation — yagni for a single-author tool — but to catch
+  # the typo class of bug:
+  #
+  #   manifest:
+  #     theme_colour: '#000'    # 🐛 should be `theme_color`
+  #
+  # …which silently no-ops and leaves the operator wondering why their
+  # PWA install icon doesn't pick up the brand colour.
+  #
+  # Strategy: known top-level keys are allow-listed below. Unknown keys
+  # warn by default (so existing sites don't break on upgrade), and
+  # raise when `ABQARI_STRICT_CONFIG=true`. CI workflows that want the
+  # gate enforced flip the env var. The plan is to flip the default to
+  # raise once the warn-mode period has passed.
+  #
+  # Reserved keys we tolerate without warning:
+  #   - `environments` is structural (per-env overrides).
+  #   - Anything beginning with `x_` is treated as a user extension
+  #     namespace, mirroring HTTP/MIME conventions. Lets a consuming
+  #     site park its own metadata in the same file without false-
+  #     positive warnings.
+  module SiteConfig
+    # Static defaults applied to every site. User values in
+    # `config/site.yml` deep-merge over these — any user-set key wins.
+    # Only static defaults belong here; dynamic ones (`minify` =
+    # `env == :production`) stay in their callers.
+    #
+    # Adding a default here removes a `config.fetch('key', value)`
+    # call elsewhere — one auditable place for the defaults the
+    # engine assumes, instead of scattered ternaries.
+    DEFAULTS = {
+      'indexable'           => true,
+      'block_ai_scraping'   => true,
+      'syntax_highlighting' => true,
+      'erb_in_markdown'     => false,
+      'theme_toggle'        => true,
+      # The default here (not buried in AssetPipeline) so EVERY reader
+      # of config['theme'] agrees. When it lived pipeline-side, a site
+      # with no `theme:` key built the minimal theme but the renderer's
+      # theme-mtime scoping read '' — so theme CSS edits rebuilt assets
+      # without re-rendering pages, and hot reload served stale hrefs.
+      'theme'               => 'minimal'
+    }.freeze
+
+    # Every top-level key the engine reads anywhere (rb + erb). Keep
+    # in lockstep with the readers — when adding a new top-level
+    # config key, add it here too. CI's audit catches drift.
+    KNOWN_KEYS = %w[
+      author
+      block_ai_scraping
+      bundle_assets
+      collections
+      contact
+      csp
+      deploy
+      description
+      drafts
+      environments
+      erb_in_markdown
+      folio
+      fonts
+      fonts_preload
+      footer
+      headers
+      home
+      icons
+      images
+      indexable
+      indieweb
+      llms
+      locale
+      manifest
+      media
+      minify
+      nav
+      newsletter
+      og_images
+      og_locale
+      pagination
+      plausible
+      robots_disallow
+      search
+      security_contact
+      share_image
+      social
+      speculation_rules
+      syndication
+      syntax_highlighting
+      syntax_theme
+      syntax_theme_dark
+      taxonomies
+      theme
+      theme_toggle
+      timezone
+      title
+      twitter
+      url
+      validate
+      visualizations
+    ].freeze
+
+    module_function
+
+    # Deep-merge DEFAULTS under the user's config. Returns a new hash;
+    # the input isn't mutated. Use at boot to fold in static defaults
+    # so call sites can do `config['key']` instead of
+    # `config.fetch('key', sane_default)`.
+    def with_defaults(config)
+      deep_merge(DEFAULTS, config || {})
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_, b, o|
+        b.is_a?(Hash) && o.is_a?(Hash) ? deep_merge(b, o) : o
+      end
+    end
+
+    def validate!(config, strict: nil, env: nil)
+      strict = ENV['ABQARI_STRICT_CONFIG'] == 'true' if strict.nil?
+
+      validate_required!(config, strict: strict, env: env)
+
+      unknown = config.keys.map(&:to_s).reject do |key|
+        KNOWN_KEYS.include?(key) || key.start_with?('x_')
+      end
+
+      return if unknown.empty?
+
+      # The advice differs by mode. The old message ended "…or set
+      # ABQARI_STRICT_CONFIG=true to make this a hard error" in BOTH
+      # branches — including the one raised *because* it was already set,
+      # which told the user to enable the thing that had just fired.
+      base = "Unknown config key(s) in site.yml: #{unknown.sort.join(', ')}. " \
+             'Typos silently no-op; add an `x_` prefix for intentional user extensions'
+
+      if strict
+        raise UserError, "#{base} (ABQARI_STRICT_CONFIG is on, so this is fatal)."
+      end
+
+      Log.warn "#{base}, or set ABQARI_STRICT_CONFIG=true to make this a hard error."
+    end
+
+    # Keys that must be present for a correct build. `title` feeds
+    # <title>, RSS, OG; a blank one ships "Page · " everywhere. `url` is
+    # the base for every absolute URL (canonical, sitemap, feed, JSON-LD)
+    # — blank in production means no sitemap, no canonical, and invalid
+    # feed URLs. Warn on a blank title always; escalate a blank `url` in
+    # production (raise under strict, warn otherwise) since a live build
+    # with no base URL is almost always a mistake.
+    def validate_required!(config, strict:, env:)
+      if config['title'].to_s.strip.empty?
+        Log.warn 'Missing `title` in site.yml — pages will render with an empty <title>.'
+      end
+
+      if config['url'].to_s.strip.empty?
+        url_msg = 'Missing `url` in site.yml — canonical URLs, sitemap, and feeds ' \
+                  'need an absolute base URL. Set `url:` (per-environment under ' \
+                  '`environments:` is fine).'
+        if env.to_s == 'production'
+          raise UserError, url_msg if strict
+
+          Log.warn url_msg
+        end
+        return
+      end
+
+      validate_url_has_no_path!(config['url'])
+    end
+
+    # Abqari emits root-relative asset and internal-link URLs (`/assets/…`,
+    # `/posts/…`, `/feed.xml`), so a `url:` with a path component
+    # (`https://user.github.io/repo`) produces a site whose every asset
+    # and link 404s under the prefix. Subdirectory/base-path deployment
+    # is not supported; fail loudly at config time instead of shipping a
+    # broken site. A bare host or a lone `/` path is fine.
+    def validate_url_has_no_path!(url)
+      parsed = begin
+        URI.parse(url.to_s)
+      rescue URI::InvalidURIError
+        nil # a malformed URL is a separate problem; don't crash here
+      end
+      return if parsed.nil?
+
+      # Check the scheme FIRST. Without one, `URI.parse('example.com')`
+      # puts the whole string in `path`, so the path check below fired
+      # and reported that `url` "has a path component ("example.com")" —
+      # technically true, humanly baffling, and pointing at the wrong
+      # mistake.
+      if parsed.scheme.to_s.empty?
+        raise UserError,
+              "`url` (#{url.inspect}) is missing a scheme. Use the full origin, " \
+              "e.g. \"https://#{url.to_s.sub(%r{\A/+}, '')}\"."
+      end
+
+      path = parsed.path.to_s
+      return if path.empty? || path == '/'
+
+      raise UserError,
+            "`url` (#{url.inspect}) has a path component (#{path.inspect}). " \
+            'Abqari does not support subdirectory/base-path deployment — every ' \
+            'asset and internal link is root-relative and would 404 under a path ' \
+            'prefix. Deploy at a domain root (a custom domain, or a `<user>.github.io` ' \
+            'root repository).'
+    end
+  end
+end

data/lib/abqari/site_loader.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+
+module Abqari
+  # Site-loading collaborator. Owns reading the three classes of input
+  # that bootstrap a build:
+  #
+  #   - `config/site.yml` (and environment overrides)
+  #   - `content/**/*.md` (every page the build will render)
+  #   - `data/**/*.{yml,yaml,json}` (operator-curated reference tables)
+  #
+  # Plus the nav/footer link cascade, which reads from both config (data/
+  # files) and frontmatter — it's loader-shaped, so it lives here too.
+  #
+  # No build-time mutation of pages happens in this class. Loaders return
+  # arrays/hashes; Site stores them. Filtering for drafts / future-dated /
+  # disabled / external-symlink pages happens at load time so downstream
+  # code sees a clean list.
+  class SiteLoader
+    def initialize(site)
+      @site = site
+    end
+
+    # Parse `config/site.yml`, apply per-environment overrides via
+    # deep-merge. Returns a Hash. No env-var coercion or schema work
+    # happens here — SiteConfig.validate! handles that downstream.
+    def load_config
+      # Site config is site-only (no engine fallback) — every consuming
+      # site declares its own theme, Folio config, etc.
+      site_root = ENV['ABQARI_SITE_ROOT'] || Dir.pwd
+      path = File.join(site_root, 'config', 'site.yml')
+      unless File.exist?(path)
+        # Silent `{}` here means "wrong directory" or a typo'd
+        # ABQARI_SITE_ROOT produces a defaults-only build with no signal.
+        # Warn loudly (and let ABQARI_STRICT_CONFIG make it fatal).
+        msg = "config/site.yml not found at #{path} — building with defaults only " \
+              '(no title, no url). Are you in the site directory?'
+        raise UserError, msg if ENV['ABQARI_STRICT_CONFIG'] == 'true'
+
+        Log.warn msg
+        return {}
+      end
+
+      raw = load_yaml_file(path) || {}
+      envs = raw.delete('environments') || {}
+      env  = @site.env.to_s
+      overrides = envs[env] || {}
+
+      warn_on_unknown_env(env, envs)
+
+      deep_merge(raw, overrides)
+    end
+
+    # `YAML.safe_load_file` with the engine-wide permitted classes, and
+    # a syntax error turned into something a person can act on.
+    #
+    # Psych's own message already names the file, line and column — the
+    # problem was that it arrived at the top of a ten-frame trace
+    # through Psych internals, which reads as an engine crash rather
+    # than "line 12 of your config has a stray colon". Keep Psych's
+    # detail, drop the frames (ABQARI_DEBUG=1 brings them back).
+    def load_yaml_file(path)
+      YAML.safe_load_file(path, permitted_classes: Abqari::YAML_PERMITTED_CLASSES)
+    rescue Psych::SyntaxError => e
+      rel = path.sub("#{@site.site_root}/", '')
+      raise UserError, "#{rel}:#{e.line}:#{e.column} — invalid YAML: #{e.problem} #{e.context}".strip
+    end
+
+    # Walk `content/**/*.md`. For each markdown file:
+    #   - Skip if it lives under a disabled collection's source dir.
+    #   - Skip if it's an external symlink (escapes site_root).
+    #   - Skip drafts unless ABQARI_INCLUDE_DRAFTS=true or drafts config
+    #     allows it in this env.
+    #   - Skip future-dated posts unless we're in dev or the env var
+    #     is set.
+    #   - Skip pages with `enabled: false` in frontmatter — total opt-out.
+    #
+    # Returns the surviving array of `Page` instances.
+    def load_pages
+      pattern = File.join(@site.site_root, 'content', '**', '*.md')
+      pages = []
+
+      Dir.glob(pattern).sort.each do |path|
+        next if disabled_collection_path?(path)
+        next if @site.external_symlink?(path)
+        next if stray_bundle_markdown?(path)
+
+        page = Page.new(path, @site)
+        next if page.disabled?
+        next if page.draft?  && !include_drafts?
+        next if page.future? && !include_future?
+
+        pages << page
+      end
+
+      pages
+    end
+
+    # True for a markdown file sitting INSIDE a bundle directory that
+    # isn't that bundle's `index.md` — e.g.
+    # `content/posts/my-post/notes.md`.
+    #
+    # A bundle is one content file plus its assets, so a second `.md`
+    # has no defined role and used to get two contradictory ones: it was
+    # copied verbatim into the output as a "bundle asset" (frontmatter
+    # and all, even when marked `published: false`), AND loaded here as
+    # a stray page rendering at `/posts/my-post/notes/` — because
+    # `Page#collection` rejects it for not being an index, leaving it
+    # uncollected rather than dropping it. Published twice, in two
+    # forms, neither intended.
+    #
+    # The asset half is fixed by the publishable-extension allow-list.
+    # This is the page half. Warn rather than skip silently: the author
+    # put the file there for a reason and needs to know it does nothing.
+    def stray_bundle_markdown?(path)
+      return false if File.basename(path) == 'index.md'
+
+      @site.collections.each do |_name, cfg|
+        next unless cfg.fetch('enabled', true)
+        next if cfg['bundle'] == false # flat collections: `<slug>.md` IS the page
+
+        source = File.join(@site.site_root, cfg['source'].to_s)
+        next unless path.start_with?(source + File::SEPARATOR)
+
+        # Depth >= 2 means it's nested inside a slug directory rather
+        # than sitting at the collection root.
+        next unless path.sub("#{source}/", '').split('/').length >= 2
+
+        rel = path.sub("#{@site.site_root}/", '')
+        Log.warn "Skipping #{rel} — only `index.md` is rendered inside a bundle " \
+                 'directory, so this file is neither published nor rendered. Move it ' \
+                 'out to publish it, or rename it with a leading dot ' \
+                 "(`.#{File.basename(path)}`) to keep it local and silence this."
+        return true
+      end
+
+      false
+    end
+
+    # Read every `data/**/*.{yml,yaml,json}` file into a hash keyed by
+    # the path-relative-with-extension-stripped form:
+    #
+    #   data/nav.yml             → result['nav']
+    #   data/foo/bar.yml         → result['foo_bar']
+    #   data/testimonials.yml    → result['testimonials']
+    #
+    # YAML files use `YAML.safe_load` with `permitted_classes:
+    # [Date, Time]` (the engine-wide allow-list) so naked dates and
+    # ISO timestamps round-trip without opening up arbitrary class
+    # instantiation.
+    def load_data
+      result = {}
+      data_dir = File.join(@site.site_root, 'data')
+      return result unless Dir.exist?(data_dir)
+
+      Dir.glob(File.join(data_dir, '**', '*.{yml,yaml,json}')).sort.each do |path|
+        rel = path.sub("#{data_dir}/", '')
+        key = rel.sub(/\.(yml|yaml|json)\z/, '').tr('/', '_')
+        result[key] = if path.end_with?('.json')
+                        begin
+                          JSON.parse(File.read(path, encoding: 'UTF-8'))
+                        rescue JSON::ParserError => e
+                          raise UserError,
+                                "data/#{rel} — invalid JSON: #{e.message.lines.first.to_s.strip}"
+                        end
+                      else
+                        load_yaml_file(path)
+                      end
+      end
+      result
+    end
+
+    # Nav cascade: data/nav.yml `links:` array > frontmatter `nav:` blocks.
+    def nav_links
+      explicit_links_from('nav') || frontmatter_links_for('nav')
+    end
+
+    # Footer cascade: same shape as nav.
+    def footer_links
+      explicit_links_from('footer') || frontmatter_links_for('footer')
+    end
+
+    private
+
+    # Warn when the operator explicitly set ABQARI_ENV to a value that
+    # doesn't match any `environments.*` key in site.yml. The most
+    # common case is a typo (`ABQARI_ENV=stage` when the config has
+    # `staging:`); the silent fall-through to the base config is
+    # surprising — the user thinks their per-env overrides are active
+    # but they aren't.
+    #
+    # Only warns when:
+    #   - ABQARI_ENV is set explicitly (not the defaulted "development")
+    #   - the config has at least one environment defined
+    #   - the requested env isn't among them
+    #
+    # Mismatches in defaulted-development mode stay silent — sites that
+    # don't define environments at all shouldn't see noise.
+    def warn_on_unknown_env(env, envs)
+      return unless ENV['ABQARI_ENV']
+      return if envs.empty?
+      return if envs.key?(env)
+
+      Log.warn(
+        "ABQARI_ENV=#{env.inspect} doesn't match any environments.* key " \
+        "in config/site.yml (defined: #{envs.keys.sort.map(&:inspect).join(', ')}). " \
+        'Falling back to the base config without env-specific overrides.'
+      )
+    end
+
+    # Layer 1 of the nav/footer cascade — explicit links array.
+    def explicit_links_from(key)
+      block = @site.data[key]
+      return nil unless block.is_a?(Hash) && block['links'].is_a?(Array)
+
+      block['links']
+    end
+
+    # Layer 2 — pages that opted in via frontmatter.
+    def frontmatter_links_for(key)
+      candidates = @site.pages.select { |page| page.frontmatter[key].is_a?(Hash) }
+      candidates.sort_by { |page| page.frontmatter[key]['order'] || Float::INFINITY }.map do |page|
+        block = page.frontmatter[key]
+        { 'label' => block['label'] || page.title, 'url' => page.url }
+      end
+    end
+
+    # True when the given source path lives under a disabled collection's
+    # source dir. Disabled collections behave as if their files don't
+    # exist — no pages, no taxonomy contributions, no nav entries.
+    def disabled_collection_path?(path)
+      @site.collections.any? do |_name, cfg|
+        next false if cfg.fetch('enabled', true)
+
+        source = File.join(@site.site_root, cfg['source'].to_s)
+        path.start_with?(source + File::SEPARATOR)
+      end
+    end
+
+    # Whether `published: false` posts render in this build.
+    #
+    # Resolution order (first match wins):
+    #   1. ABQARI_INCLUDE_DRAFTS=true → always include
+    #   2. Production → never include (drafts must not leak to live)
+    #   3. Development → `drafts.show_in_development` config (default true)
+    def include_drafts?
+      return true if ENV['ABQARI_INCLUDE_DRAFTS'] == 'true'
+      return false if @site.env == :production
+
+      @site.config.dig('drafts', 'show_in_development') != false
+    end
+
+    def include_future?
+      ENV['ABQARI_INCLUDE_FUTURE'] == 'true' || @site.env != :production
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_, b, o|
+        b.is_a?(Hash) && o.is_a?(Hash) ? deep_merge(b, o) : o
+      end
+    end
+  end
+end

data/lib/abqari/sitemap.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Abqari
+  class Sitemap
+    XMLNS = 'http://www.sitemaps.org/schemas/sitemap/0.9'
+    XMLNS_IMAGE = 'http://www.google.com/schemas/sitemap-image/1.1'
+
+    def initialize(site)
+      @site = site
+    end
+
+    def write
+      base = @site.config['url']
+      return unless base
+
+      File.write(File.join(@site.output_dir, 'sitemap.xml'), build(base))
+    end
+
+    private
+
+    def build(base)
+      base = base.sub(%r{/\z}, '')
+      urls = @site.all_pages.map { |page| url_entry(base, page) }.compact
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <urlset xmlns="#{XMLNS}" xmlns:image="#{XMLNS_IMAGE}">
+        #{urls.join("\n")}
+        </urlset>
+      XML
+    end
+
+    def url_entry(base, page)
+      return nil if skip?(page)
+
+      lines = ['  <url>', "    <loc>#{xml_escape("#{base}#{page.url}")}</loc>"]
+
+      lastmod = format_lastmod(page)
+      lines << "    <lastmod>#{lastmod}</lastmod>" if lastmod
+
+      images_for(page).each do |image_url_path|
+        # `Page#bundle_images` returns URL paths (not filesystem
+        # paths) consistently — bundle assets are converted via
+        # `page.url + basename`, frontmatter absolute paths pass
+        # through as-is, externals are filtered out. So we just
+        # prepend the site base.
+        lines << '    <image:image>'
+        lines << "      <image:loc>#{xml_escape("#{base}#{image_url_path}")}</image:loc>"
+        lines << '    </image:image>'
+      end
+
+      lines << '  </url>'
+      lines.join("\n")
+    end
+
+    def skip?(page)
+      return true unless page.url
+      return false unless page.respond_to?(:frontmatter)
+      return true if page.frontmatter['sitemap'] == false
+      # A page that tells crawlers `noindex` shouldn't also be advertised
+      # in the sitemap — the two signals contradict each other and
+      # Search Console flags it.
+      return true if page.frontmatter['robots'].to_s.include?('noindex')
+
+      false
+    end
+
+    def format_lastmod(page)
+      stamp = page.respond_to?(:lastmod) ? page.lastmod : nil
+      stamp&.strftime('%Y-%m-%d')
+    end
+
+    def images_for(page)
+      page.respond_to?(:bundle_images) ? page.bundle_images : []
+    end
+
+    # Page URLs are constrained by `PERMALINK_ALLOWED` to URL-safe
+    # ASCII, so the practical risk is the `base` URL or a frontmatter
+    # image path carrying `&`/`<`/`>`. Escape every interpolation so
+    # one stray ampersand can't poison the whole feed.
+    def xml_escape(text)
+      CGI.escapeHTML(text.to_s)
+    end
+  end
+end

data/lib/abqari/speculation_rules_guard.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'base64'
+
+module Abqari
+  # Tiny inline `<script>` that respects user opt-outs from background
+  # prefetching/prerendering. Reads three signals; if any is on, the
+  # `<script type="speculationrules">` block in the head gets removed
+  # before the browser acts on it:
+  #
+  #   1. `prefers-reduced-data: reduce` — CSS media query (Chrome
+  #      supports it; Safari doesn't but treats it as no-match).
+  #   2. `navigator.connection.saveData` — JS flag set when the user
+  #      has Save-Data on in their browser data settings.
+  #   3. (Implicit) `navigator.connection.effectiveType === 'slow-2g'`
+  #      or `'2g'` — very slow connections get the same opt-out.
+  #
+  # Stable single-line string so the SHA256 hash is constant across
+  # builds; HeadersFile adds the hash to the CSP script-src list so
+  # strict CSP still allows this one inline script.
+  module SpeculationRulesGuard
+    SCRIPT = "(function(){try{var c=navigator.connection;var saveData=c&&c.saveData;var slow=c&&(c.effectiveType==='slow-2g'||c.effectiveType==='2g');var reducedData=window.matchMedia&&window.matchMedia('(prefers-reduced-data: reduce)').matches;if(saveData||slow||reducedData){var s=document.getElementById('abqari-spec-rules');if(s)s.remove()}}catch(e){}})()"
+    SHA256 = "sha256-#{Base64.strict_encode64(Digest::SHA256.digest(SCRIPT))}"
+  end
+end