abqari 1.1.0

data/lib/abqari/publication_normaliser.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Abqari
+  # Normalises publication / bundle / series frontmatter into the
+  # canonical Folio-aligned shape documented in `docs/publications.md`.
+  # Runs once at frontmatter-parse time so the rest of the engine sees
+  # one vocabulary.
+  #
+  # Today the normalisers do small, contained work:
+  #
+  #   - `PublicationNormaliser` expands `price: "$16.00"` shorthand
+  #     into the canonical `{ cents:, currency:, formatted: }` Hash
+  #     so authors can write the prettier form without losing the
+  #     Folio-aligned shape downstream.
+  #   - `BundleNormaliser` and `SeriesNormaliser` do the same price
+  #     expansion. Bundle / series use `name` (not `title`); no
+  #     translation needed — frontmatter already writes `name`.
+  #
+  # Adding a new shorthand later: each normaliser is a single function
+  # that takes a hash and returns a hash. Keep them idempotent so a
+  # frontmatter block already in canonical form passes through
+  # unchanged.
+  module PublicationNormaliser
+    # Symbol → ISO currency code. Falls back to USD for unknown
+    # symbols (matches Folio's serializer default).
+    CURRENCY_SYMBOLS = {
+      '$'  => 'USD',
+      'A$' => 'AUD',
+      'C$' => 'CAD',
+      'NZ$' => 'NZD',
+      'S$' => 'SGD',
+      '£'  => 'GBP',
+      '€'  => 'EUR',
+      '¥'  => 'JPY'
+    }.freeze
+    # Order matters — longest symbols first so 'A$' / 'S$' / 'NZ$' /
+    # 'C$' match before the bare '$'.
+    SYMBOL_ORDER = CURRENCY_SYMBOLS.keys.sort_by { |s| -s.length }
+
+    PRICE_RE = /\A\s*(?<symbol>#{SYMBOL_ORDER.map { |s| Regexp.escape(s) }.join('|')})?\s*(?<amount>\d+(?:\.\d+)?)\s*\z/
+
+    module_function
+
+    # Top-level entry point. Dispatches per collection. Returns the
+    # frontmatter hash with shorthand fields expanded; original input
+    # not mutated.
+    #
+    # Publications, bundles, AND series all get price normalisation.
+    # Folio doesn't supply prices on series (series in Folio are pure
+    # sequences, no commerce), but a native author CAN set
+    # `price: "$28.00"` on a series to render a "buy the whole
+    # series" button — and the rest of the engine reads
+    # `fm.dig('price', 'formatted')`, so the shorthand needs to
+    # expand here regardless of source.
+    def call(frontmatter, collection)
+      return frontmatter unless frontmatter.is_a?(Hash)
+
+      case collection
+      when 'publications', 'bundles', 'series' then normalise_with_price(frontmatter)
+      else frontmatter
+      end
+    end
+
+    def normalise_with_price(frontmatter)
+      return frontmatter unless frontmatter['price']
+      return frontmatter if frontmatter['price'].is_a?(Hash)
+
+      expanded = expand_price(frontmatter['price'])
+      return frontmatter unless expanded
+
+      frontmatter.merge('price' => expanded)
+    end
+
+    # Expand a string price into the canonical Hash shape:
+    #   "$16.00"  => { cents: 1600, currency: 'USD', formatted: '$16.00' }
+    #   "12"      => { cents: 1200, currency: 'USD', formatted: '$12.00' }
+    #   "£9.99"   => { cents: 999,  currency: 'GBP', formatted: '£9.99'  }
+    #
+    # Returns nil if the string doesn't parse (caller leaves the
+    # frontmatter value as-is, so the operator sees their typo
+    # surface downstream — e.g. JSON-LD will omit the offer).
+    def expand_price(raw)
+      return nil if raw.nil? || raw.to_s.strip.empty?
+
+      raw_str = raw.to_s.strip
+      match = PRICE_RE.match(raw_str)
+      return nil unless match
+
+      symbol = match[:symbol]
+      currency = CURRENCY_SYMBOLS[symbol] || 'USD'
+      amount = match[:amount].to_f
+      cents  = (amount * 100).round
+      # When the author wrote a bare number ("12"), supply a default
+      # formatted form so display code doesn't see "12" with no
+      # currency marker. The symbol is the canonical one for the
+      # inferred currency.
+      formatted = if symbol
+                    raw_str
+                  else
+                    default_symbol = CURRENCY_SYMBOLS.invert[currency] || '$'
+                    "#{default_symbol}#{format('%.2f', amount)}"
+                  end
+
+      {
+        'cents'     => cents,
+        'currency'  => currency,
+        'formatted' => formatted
+      }
+    end
+  end
+end

data/lib/abqari/publisher_pages.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Abqari
+  # Auto-generates index + show pages for publications, bundles, and
+  # series whose data comes from an external publisher integration
+  # (currently Folio — `apps/folio` — with the door open for others
+  # that emit canonical-shape data per docs/publications.md).
+  #
+  # Runs only when `folio:` config is set (today). Each generated page
+  # can be overridden by creating a markdown file at the matching path
+  # (e.g. `content/publications/<slug>/index.md`); the engine skips
+  # auto-generation for any URL that already has a Page from
+  # `content/`. The override page wins on slug collision.
+  class PublisherPages
+    def initialize(site)
+      @site = site
+    end
+
+    def enabled?
+      @site.config['folio'].is_a?(Hash) && !@site.config['folio'].empty?
+    end
+
+    # Returns auto-generated pages: up to three index pages (publications
+    # / bundles / series) and one show page per externally-sourced
+    # publication, bundle, and series.
+    def pages
+      return [] unless enabled?
+
+      result = []
+      result.concat(index_pages)
+      result.concat(publication_pages)
+      result.concat(bundle_pages)
+      result.concat(series_pages)
+      result
+    end
+
+    private
+
+    def existing_urls
+      @existing_urls ||= @site.pages.map(&:url).to_set
+    end
+
+    # The collection-permalink-derived index URL for a kind. Honors the
+    # collection's `slug:` aliasing. Falls back to /<kind>/ when there's
+    # no permalink defined (shouldn't happen for built-in kinds).
+    def kind_url_prefix(collection_name, fallback)
+      cfg = @site.collection_config(collection_name)
+      slug = cfg['slug'].to_s
+      return "/#{slug}/" unless slug.empty?
+      perm = cfg['permalink'].to_s
+      perm.empty? ? "/#{fallback}/" : perm.sub(':slug/', '').sub(':slug', '')
+    end
+
+    # Generate one index page per kind (publications / bundles /
+    # series). Skip when:
+    #   - The user has a hand-written page at that URL (their override wins).
+    #   - The publisher returned zero items for the kind — auto-
+    #     generating an empty `/series/` placeholder isn't useful.
+    #     The page reappears the moment the publisher returns at
+    #     least one item.
+    #
+    # Manual-only sites (no publisher configured) get no auto-index
+    # here — but the bundles_index / book_series_index layouts read
+    # from `site.collection(...)`, so a user who creates
+    # `content/bundles/index.md` (or `content/series/index.md`) sees
+    # their manual entries listed without any further wiring.
+    def index_pages
+      kinds = [
+        { name: 'publications', layout: 'publications_index', data: 'folio_publications' },
+        { name: 'bundles',      layout: 'bundles_index',      data: 'folio_bundles'      },
+        { name: 'series',       layout: 'book_series_index',  data: 'folio_series'       }
+      ]
+      kinds.filter_map do |kind|
+        url = kind_url_prefix(kind[:name], kind[:name])
+        next if existing_urls.include?(url)
+        next if (@site.data[kind[:data]] || {}).empty?
+
+        PublisherIndexPage.new(@site, kind[:name], kind[:layout], url)
+      end
+    end
+
+    # Externally-sourced publications → pages in the `publications`
+    # collection. Layout comes from the collection config so
+    # `publications.layout: book` (or default `publication`) routes
+    # through the right template.
+    def publication_pages
+      cfg = @site.collection_config('publications')
+      url_prefix = kind_url_prefix('publications', 'publications')
+      layout = cfg['layout'] || 'publication'
+
+      Array(@site.data['folio_publications']).filter_map do |slug, pub|
+        url = "#{url_prefix}#{slug}/"
+        next if existing_urls.include?(url)
+
+        PublisherShowPage.new(@site, kind: 'publication', slug: slug, data: pub, layout: layout, url: url)
+      end
+    end
+
+    def bundle_pages
+      cfg = @site.collection_config('bundles')
+      url_prefix = kind_url_prefix('bundles', 'bundles')
+      layout = cfg['layout'] || 'bundle'
+
+      Array(@site.data['folio_bundles']).filter_map do |slug, bundle|
+        url = "#{url_prefix}#{slug}/"
+        next if existing_urls.include?(url)
+
+        PublisherShowPage.new(@site, kind: 'bundle', slug: slug, data: bundle, layout: layout, url: url)
+      end
+    end
+
+    def series_pages
+      cfg = @site.collection_config('series')
+      url_prefix = kind_url_prefix('series', 'series')
+      layout = cfg['layout'] || 'series'
+
+      Array(@site.data['folio_series']).filter_map do |slug, series|
+        url = "#{url_prefix}#{slug}/"
+        next if existing_urls.include?(url)
+
+        PublisherShowPage.new(@site, kind: 'series', slug: slug, data: series, layout: layout, url: url)
+      end
+    end
+  end
+
+  # Index page for a kind (publications / bundles / series). Renders
+  # the matching collection-index layout, which iterates the merged
+  # `site.collection(name)` (manual + externally-sourced).
+  class PublisherIndexPage
+    attr_reader :site, :kind
+
+    def initialize(site, kind, layout, url)
+      @site   = site
+      @kind   = kind
+      @layout = layout
+      @url    = url
+    end
+
+    def title
+      @kind.capitalize
+    end
+
+    def description
+      "All #{@kind}."
+    end
+
+    def content
+      ''
+    end
+
+    def frontmatter
+      {}
+    end
+
+    def url
+      @url
+    end
+
+    # Bounded-trust external data per docs/security.md §1. The `slug`
+    # flows into this URL — route through `PathSafe` so a hostile or
+    # accidental `"slug": "../../etc"` raises a build error instead
+    # of writing outside `_site/`.
+    def output_path
+      PathSafe.join_under(@site.output_dir, @url.sub(%r{\A/}, '').chomp('/'), 'index.html')
+    end
+
+    def write
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, @site.post_process(render, page: self))
+    end
+
+    def layout_name
+      @layout
+    end
+
+    def needs_render?
+      return true unless File.exist?(output_path)
+
+      output_mtime = File.mtime(output_path)
+      return true if output_mtime < @site.shared_deps_mtime
+      # Layouts are tracked per-page rather than in GLOBAL_DEP_GLOBS —
+      # without this, editing `publications_index.html.erb` left the
+      # index stale on the dev server.
+      @site.layout_deps_mtime(layout_name) > output_mtime
+    end
+
+    def lastmod
+      Time.now
+    end
+
+    def bundle_images
+      []
+    end
+
+    private
+
+    def render
+      RenderContext.new(self, @site).render_layout(layout_name)
+    end
+  end
+
+  # Show page for a single externally-sourced publication / bundle /
+  # series. Looks like a regular `Page` to the rest of the engine —
+  # same `frontmatter`, `title`, `description`, `collection` interface
+  # — so templates iterate `site.collection('publications')` (etc.)
+  # and don't need to know whether a particular entry came from
+  # `content/` or an external publisher.
+  #
+  # The publisher's payload IS the frontmatter — the canonical schema
+  # (docs/publications.md) lines up with what the publisher emits, so
+  # no translation layer is needed.
+  class PublisherShowPage
+    # Map `kind:` to the collection name `site.collection` exposes.
+    KIND_TO_COLLECTION = {
+      'publication' => 'publications',
+      'bundle'      => 'bundles',
+      'series'      => 'series'
+    }.freeze
+
+    attr_reader :site, :kind, :slug, :data
+
+    def initialize(site, kind:, slug:, data:, layout:, url:)
+      @site   = site
+      @kind   = kind
+      @slug   = slug
+      @data   = data
+      @layout = layout
+      @url    = url
+    end
+
+    # Collection membership. Returns `'publications'` / `'bundles'` /
+    # `'series'`, which lets `Site#collection(name)` include this page
+    # in its iteration alongside manual Pages.
+    def collection
+      KIND_TO_COLLECTION[@kind.to_s]
+    end
+
+    # Publications use `title`; bundles + series use `name` (matches
+    # Folio's vocabulary — see docs/publications.md). Falls back to
+    # the slug so callers always get a string.
+    def title
+      @data['title'] || @data['name'] || @slug
+    end
+
+    # Page short-summary text — used by sitemap, RSS, OG, JSON-LD.
+    # Per docs/publications.md: publications use `tagline` then
+    # `excerpt`; bundles + series use `description`. The first line
+    # keeps it summary-shaped.
+    def description
+      raw = case collection
+            when 'publications'
+              @data['tagline'] || @data['excerpt']
+            else
+              @data['description']
+            end
+      raw.to_s.lines.first&.strip
+    end
+
+    def content
+      ''
+    end
+
+    # The data payload IS the frontmatter. No bookkeeping keys — the
+    # canonical schema covers everything templates need to know;
+    # templates can't and shouldn't care whether the data came from
+    # an external publisher.
+    def frontmatter
+      @data
+    end
+
+    def url
+      @url
+    end
+
+    # See PublisherIndexPage#output_path — same trust boundary, same routing.
+    def output_path
+      PathSafe.join_under(@site.output_dir, @url.sub(%r{\A/}, '').chomp('/'), 'index.html')
+    end
+
+    def write
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, @site.post_process(render, page: self))
+    end
+
+    def layout_name
+      @layout
+    end
+
+    def needs_render?
+      return true unless File.exist?(output_path)
+
+      output_mtime = File.mtime(output_path)
+      return true if @site.shared_deps_mtime > output_mtime
+      # Layouts are tracked per-page rather than in GLOBAL_DEP_GLOBS —
+      # without this, editing `publication.html.erb` left every show
+      # page stale on the dev server.
+      return true if @site.layout_deps_mtime(layout_name) > output_mtime
+
+      # If the publisher cache is newer than this page's output, re-render —
+      # the underlying data may have changed since last build.
+      cache_path = folio_cache_path
+      cache_path && File.exist?(cache_path) && File.mtime(cache_path) > output_mtime
+    end
+
+    def lastmod
+      cache_path = folio_cache_path
+      cache_path && File.exist?(cache_path) ? File.mtime(cache_path) : Time.now
+    end
+
+    # On-disk Folio cache backing this page's kind.
+    #
+    # Derived from KIND_TO_COLLECTION rather than pluralising `kind`.
+    # `"#{kind}s.yml"` gets publications and bundles right and produces
+    # `seriess.yml` for series — a file that never exists, so series
+    # pages never noticed a stale cache (no re-render when Folio data
+    # changed) and fell through to the `Time.now` lastmod, restamping
+    # every series page's sitemap entry on every build. The determinism
+    # test couldn't catch it: both builds run on the same day.
+    #
+    # The collection names ARE the cache basenames, so reusing the map
+    # keeps the two from drifting again.
+    def folio_cache_path
+      basename = KIND_TO_COLLECTION[@kind.to_s]
+      return nil unless basename
+
+      File.join(@site.site_root, 'vendor', 'folio', "#{basename}.yml")
+    end
+
+    def bundle_images
+      []
+    end
+
+    private
+
+    def render
+      RenderContext.new(self, @site).render_layout(layout_name)
+    end
+  end
+
+end

data/lib/abqari/redirects.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'set'
+
+module Abqari
+  class Redirects
+    def initialize(site)
+      @site = site
+    end
+
+    def write
+      mappings = collect
+      return if mappings.empty?
+
+      mappings.each { |from, to| write_stub(from, to) }
+      write_redirects_file(mappings)
+    end
+
+    private
+
+    def collect
+      # URLs of every real page in the build. A `redirect_from:` that
+      # collides with one of these would overwrite that page's
+      # index.html with a meta-refresh stub (write_deploy_artifacts runs
+      # AFTER render_pages) — silently deleting published content, or
+      # creating a self-referential redirect loop when it matches the
+      # page's own URL. Fail loudly instead.
+      page_urls = @site.all_pages.map { |p| p.url if p.respond_to?(:url) }.compact.to_set
+
+      result = {}
+      @site.all_pages.each do |page|
+        next unless page.respond_to?(:frontmatter)
+
+        Array(page.frontmatter['redirect_from']).each do |from|
+          # A `from` with whitespace (or control chars) corrupts the
+          # space-delimited `_redirects` file — `/old page/ /new/ 301`
+          # parses as four fields. Reject it at source with the offending
+          # file named.
+          if from.to_s.match?(/[[:space:][:cntrl:]]/)
+            raise "redirect_from #{from.inspect} in #{describe(page)} contains whitespace/control " \
+                  'characters, which would corrupt the _redirects file. Use a URL-safe path.'
+          end
+
+          key = normalise(from)
+
+          if key == page.url
+            raise "redirect_from #{from.inspect} in #{describe(page)} points at the page's own URL " \
+                  "(#{page.url}) — this would create an infinite redirect loop"
+          end
+          if page_urls.include?(key)
+            raise "redirect_from #{from.inspect} in #{describe(page)} collides with an existing page " \
+                  "at #{key} — the redirect stub would overwrite that page. Choose a different source path."
+          end
+          if result.key?(key) && result[key] != page.url
+            raise "redirect_from #{from.inspect} is declared twice with different targets " \
+                  "(#{result[key]} and #{page.url}). Each source path may redirect to only one place."
+          end
+
+          result[key] = page.url
+        end
+      end
+      result
+    end
+
+    # Best-effort human identifier for a page in an error message —
+    # generated pages have no source_path, so fall back to the URL.
+    def describe(page)
+      if page.respond_to?(:source_path) && page.source_path
+        page.source_path
+      else
+        page.url
+      end
+    end
+
+    def normalise(path)
+      path = "/#{path}" unless path.start_with?('/')
+      path = "#{path}/" unless path.end_with?('/') || File.extname(path).length.positive?
+      path
+    end
+
+    # `from` is user input (frontmatter `redirect_from:`). Route through
+    # PathSafe so a hostile or accidental `redirect_from: ../../etc`
+    # can't write the stub outside `_site/`. Same invariant as
+    # Page#output_path — every user-input → filesystem path goes
+    # through `PathSafe.join_under` (docs/security.md §2).
+    def write_stub(from, to)
+      relative = from.sub(%r{\A/}, '').sub(%r{/\z}, '')
+      # A `from` that carries a file extension (`/old-page.html`) is a
+      # literal file path — write the stub AT that path, not at
+      # `old-page.html/index.html` (which serves at `/old-page.html/`,
+      # a different URL). Extension-less sources are pretty-URL
+      # directories and get an index.html.
+      dest = if File.extname(relative).empty?
+               PathSafe.join_under(@site.output_dir, relative, 'index.html')
+             else
+               PathSafe.join_under(@site.output_dir, relative)
+             end
+      FileUtils.mkdir_p(File.dirname(dest))
+
+      base = @site.config['url']&.sub(%r{/\z}, '')
+      canonical = base ? "#{base}#{to}" : to
+
+      # Escape every interpolation. `to` and `canonical` flow into HTML
+      # attributes and text content; both author-controlled today, but
+      # the redirect path is the only stub-emitter that didn't escape,
+      # so close that gap for symmetry.
+      to_attr        = Helpers.h(to)
+      canonical_attr = Helpers.h(canonical)
+      to_text        = Helpers.h(to)
+
+      File.write(dest, <<~HTML)
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+          <meta charset="UTF-8">
+          <meta http-equiv="refresh" content="0; url=#{to_attr}">
+          <link rel="canonical" href="#{canonical_attr}">
+          <meta name="robots" content="noindex">
+          <title>Redirecting…</title>
+        </head>
+        <body data-pagefind-ignore>
+          <p>This page has moved to <a href="#{to_attr}">#{to_text}</a>.</p>
+        </body>
+        </html>
+      HTML
+    end
+
+    def write_redirects_file(mappings)
+      lines = mappings.map { |from, to| "#{from} #{to} 301" }
+      File.write(File.join(@site.output_dir, '_redirects'), "#{lines.join("\n")}\n")
+    end
+  end
+end

data/lib/abqari/related_index_page.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Abqari
+  # Auto-generated index page that lists ALL related items for a source
+  # page, used when there are more matches than fit in the show-view's
+  # `related.limit` block. URL is `/<source url>related/`, e.g.
+  # `/posts/writing-in-markdown/related/`.
+  #
+  # Generated only when `total_related > limit` — pages with zero or
+  # few related items don't get an index page (the show-view block
+  # already shows everything). Site#generate_related_pages handles the
+  # decision and creation.
+  class RelatedIndexPage
+    attr_reader :site, :source_page, :related_items
+
+    def initialize(source_page, site, related_items)
+      @source_page = source_page
+      @site = site
+      @related_items = related_items
+    end
+
+    def title
+      "Related to #{@source_page.title}"
+    end
+
+    def description
+      "All items related to '#{@source_page.title}' — ranked by tag, series, and category overlap."
+    end
+
+    def content
+      ''
+    end
+
+    def frontmatter
+      {}
+    end
+
+    def tags
+      []
+    end
+
+    def url
+      "#{@source_page.url.chomp('/')}/related/"
+    end
+
+    def output_path
+      File.join(@site.output_dir, url.sub(%r{\A/}, '').chomp('/'), 'index.html')
+    end
+
+    def lastmod
+      @related_items.map(&:lastmod).compact.max || @source_page.lastmod
+    end
+
+    def bundle_images
+      []
+    end
+
+    # Re-render when shared deps change or when the source page or any
+    # related item has been touched. Conservatively: always re-render
+    # when shared deps change — the related list could shift if any
+    # post in the collection changed its tags/series.
+    def needs_render?
+      true
+    end
+
+    def write
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, @site.post_process(render, page: self))
+    end
+
+    private
+
+    def render
+      RenderContext.new(self, @site).render_layout('related_index')
+    end
+  end
+end