abqari 1.1.0

data/lib/abqari/visualizations.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+
+module Abqari
+  # D3-based data visualizations of your site's content. Off by default —
+  # toggle in config/site.yml under `visualizations:`. When enabled, abqari
+  # generates per-viz JSON data files and HTML pages at build time. The
+  # viz pages load D3 (vendored at /assets/d3/d3.v7.min.js) and the
+  # corresponding JSON, then render entirely client-side.
+  #
+  # Three visualizations ship:
+  #   - tag-bubble:           circle-pack of tags sized by post count
+  #   - tag-cooccurrence:     chord diagram of tags that appear together
+  #   - topic-constellation:  force graph of posts connected by shared tags
+  #
+  # Each is independently config-toggleable. When all are off, no JSON is
+  # written, no pages are generated, D3 isn't pulled into the asset pipeline.
+  class Visualizations
+    VIZ_NAMES = %w[tag-bubble tag-cooccurrence topic-constellation].freeze
+
+    def initialize(site)
+      @site = site
+    end
+
+    def enabled?
+      enabled_visualizations.any?
+    end
+
+    def enabled_visualizations
+      config = @site.config['visualizations'] || {}
+      VIZ_NAMES.select { |name| config[name.tr('-', '_')] == true }
+    end
+
+    # Generated VizPage instances — appended to Site's @generated_pages so
+    # they go through the normal render pipeline (post-process, minification,
+    # incremental check, etc.).
+    def pages
+      enabled_visualizations.map { |name| VizPage.new(name, @site) }
+    end
+
+    # Writes the JSON data files. Called from Site#build after pages render.
+    def write_data
+      return unless enabled?
+
+      enabled_visualizations.each { |name| write_one(name) }
+    end
+
+    private
+
+    def write_one(name)
+      data = case name
+             when 'tag-bubble'           then tag_bubble_data
+             when 'tag-cooccurrence'     then tag_cooccurrence_data
+             when 'topic-constellation'  then topic_constellation_data
+             end
+
+      dest = File.join(@site.output_dir, 'visualizations', "#{name}.json")
+      FileUtils.mkdir_p(File.dirname(dest))
+      File.write(dest, JSON.pretty_generate(data))
+    end
+
+    # Tag bubble — array of { name, note_count } (note_count for parity with
+    # Cogent's chart code; conceptually it's "post_count" here).
+    def tag_bubble_data
+      tags = @site.posts_by_term('tags').map do |tag, posts|
+        { 'name' => tag, 'note_count' => posts.size }
+      end.sort_by { |t| -t['note_count'] }
+
+      { 'tags' => tags }
+    end
+
+    # Tag co-occurrence — square matrix where matrix[i][j] is the number of
+    # posts that have both tags[i] and tags[j].
+    #
+    # Previously O(tags² × posts_per_tag): the inner cell did an Array
+    # membership scan against the second tag's post list. For a tag
+    # cloud with 200 tags and a thousand posts the cost is multiple
+    # seconds, all inside the build's render phase.
+    #
+    # Now: convert each tag's post list to a Set once (O(posts)), then
+    # compute each cell as a Set intersection (O(min(set sizes))).
+    # Cells below the diagonal mirror the cells above it — compute the
+    # upper triangle once and copy.
+    def tag_cooccurrence_data
+      grouped = @site.posts_by_term('tags')
+      tags    = grouped.keys.sort
+      sets    = grouped.transform_values { |posts| posts.to_set }
+
+      size   = tags.size
+      matrix = Array.new(size) { Array.new(size, 0) }
+
+      tags.each_with_index do |tag_a, i|
+        ((i + 1)...size).each do |j|
+          shared = (sets[tag_a] & sets[tags[j]]).size
+          matrix[i][j] = shared
+          matrix[j][i] = shared
+        end
+      end
+
+      { 'tags' => tags, 'matrix' => matrix }
+    end
+
+    # Topic constellation — nodes are posts, links connect posts that share
+    # at least one tag. Link weight = number of shared tags.
+    def topic_constellation_data
+      posts = @site.posts
+      nodes = posts.map do |post|
+        {
+          'id' => post.url,
+          'title' => post.title,
+          'tags' => post.tags,
+          'date' => post.date&.iso8601
+        }.compact
+      end
+
+      links = []
+      posts.each_with_index do |a, i|
+        posts[(i + 1)..].each do |b|
+          shared = a.tags & b.tags
+          next if shared.empty?
+
+          links << { 'source' => a.url, 'target' => b.url, 'weight' => shared.size }
+        end
+      end
+
+      { 'nodes' => nodes, 'links' => links }
+    end
+  end
+
+  # A single visualization page. Generated by Visualizations#pages and added
+  # to Site's @generated_pages, so it renders through the normal pipeline.
+  class VizPage
+    TITLES = {
+      'tag-bubble' => 'Tag Bubble',
+      'tag-cooccurrence' => 'Tag Co-occurrence',
+      'topic-constellation' => 'Topic Constellation'
+    }.freeze
+
+    DESCRIPTIONS = {
+      'tag-bubble' => 'Each tag rendered as a circle, sized by the number of posts using it.',
+      'tag-cooccurrence' => 'Which tags appear together — chord diagram of tag overlap across posts.',
+      'topic-constellation' => 'Posts as nodes, connected by shared tags. Drag to explore.'
+    }.freeze
+
+    attr_reader :viz_name, :site
+
+    def initialize(viz_name, site)
+      @viz_name = viz_name
+      @site = site
+    end
+
+    def title
+      TITLES[viz_name]
+    end
+
+    def description
+      DESCRIPTIONS[viz_name]
+    end
+
+    def content
+      ''
+    end
+
+    def frontmatter
+      {}
+    end
+
+    def url
+      "/visualizations/#{viz_name}/"
+    end
+
+    def output_path
+      File.join(@site.output_dir, 'visualizations', viz_name, 'index.html')
+    end
+
+    def write
+      FileUtils.mkdir_p(File.dirname(output_path))
+      File.write(output_path, @site.post_process(render, page: self))
+    end
+
+    # Used by Site's incremental render: re-render when shared deps change
+    # or any post changes (since post data feeds the JSON).
+    def layout_name
+      'visualization'
+    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 live outside GLOBAL_DEP_GLOBS and are tracked per-page;
+      # only Page consulted them, so editing this layout rebuilt nothing.
+      return true if @site.layout_deps_mtime(layout_name) > output_mtime
+
+      @site.posts.any? { |post| (post.lastmod || Time.now) > output_mtime }
+    end
+
+    def lastmod
+      @site.posts.map(&:lastmod).compact.max
+    end
+
+    def bundle_images
+      []
+    end
+
+    private
+
+    def render
+      RenderContext.new(self, @site).render_layout(layout_name)
+    end
+  end
+end

data/lib/abqari.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+# VERSION lives in its own dependency-free file so `abqari.gemspec` can
+# read it without loading the engine (and with it every runtime gem).
+require_relative 'abqari/version'
+
+module Abqari
+  ROOT = File.expand_path('..', __dir__)
+
+  # An expected, actionable failure: the user mistyped a config key,
+  # left invalid YAML in a file, passed a bad flag. NOT an engine bug.
+  #
+  # The distinction is the whole point. Entry points print these as a
+  # plain message and exit 1; everything else keeps its backtrace,
+  # because an unexpected exception is a defect and hiding its trace
+  # makes it unreportable. Raising `UserError` is therefore a claim:
+  # "the message alone tells the user what to fix."
+  class UserError < StandardError; end
+
+  # Wrap a CLI entry point so failures are presented rather than dumped.
+  #
+  # A malformed `config/site.yml` used to greet the user with ten frames
+  # of Psych internals; the useful part (file, line, column) was there,
+  # just buried at the top. Same for a typo'd flag. Set ABQARI_DEBUG=1
+  # to get the backtrace back when a UserError is hiding something real.
+  #
+  # Interrupt is handled here too: Ctrl-C during a build printed a stack
+  # trace through the render pool, which reads like a crash rather than
+  # "you pressed Ctrl-C". Exit 130 is the shell convention for SIGINT.
+  def self.run_cli
+    yield
+  rescue UserError => e
+    warn e.message
+    warn '' if debug?
+    warn e.backtrace.join("\n") if debug?
+    exit 1
+  rescue Interrupt
+    warn "\nInterrupted."
+    exit 130
+  end
+
+  def self.debug?
+    %w[1 true yes].include?(ENV['ABQARI_DEBUG'].to_s.strip.downcase)
+  end
+
+  # Classes the engine accepts from any YAML input — site config,
+  # data files, frontmatter, Folio cache, audit whitelists. Date +
+  # Time so naked dates like `date: 2026-06-15` and ISO timestamps
+  # round-trip. Anything else (Symbol, ranges, arbitrary classes)
+  # raises Psych::DisallowedClass before any deserialised object
+  # touches the engine. Keep this set minimal — adding a class here
+  # is the security-sensitive equivalent of widening a sandbox.
+  YAML_PERMITTED_CLASSES = [Date, Time].freeze
+
+  # Marker file written by `Site#build` at the end of a successful
+  # build. Deployers (`bin/deploy`, CI pipelines that rsync `_site/`)
+  # refuse to ship without it; the test harness uses it as the
+  # fixture-intact sentinel. Single source of truth so the three
+  # readers stay in lockstep.
+  BUILD_OK_SENTINEL = '.abqari-build-ok'
+
+  # Atomic file write: write to a sibling tempfile, fsync, then
+  # rename into place. POSIX guarantees the rename is atomic on the
+  # same filesystem, so a reader either sees the previous full
+  # contents or the new full contents — never a half-written buffer.
+  #
+  # Used for state files we re-read on subsequent builds: the
+  # POSSE sent log, the webmention sender log, the webmention
+  # cache, the etag pointer. Without atomicity, a SIGINT or
+  # runner timeout mid-write leaves a truncated YAML / JSON file
+  # and the next build either crashes on parse or — worse for the
+  # POSSE case — treats every prior send as un-sent and re-posts
+  # everything to Mastodon + Bluesky.
+  def self.atomic_write(path, content)
+    dir  = File.dirname(path)
+    base = File.basename(path)
+    tmp  = File.join(dir, ".#{base}.#{Process.pid}.tmp")
+    File.open(tmp, 'w') do |f|
+      f.write(content)
+      f.flush
+      f.fsync rescue nil
+    end
+    File.rename(tmp, path)
+  ensure
+    File.unlink(tmp) if tmp && File.exist?(tmp) rescue nil
+  end
+
+  # Jekyll-style YAML frontmatter — opening `---`, body, closing
+  # `---`, then everything after.
+  #
+  # Match groups:
+  #   [1] = the YAML body between the `---` markers
+  #   [2] = everything after the closing `---\n` (page body / layout
+  #         markup / whatever follows)
+  #
+  # The YAML group is OPTIONAL (`(?:.*?\n)?`) so an EMPTY frontmatter
+  # block (`---\n---\n`) still matches — group [1] is "" (→ `{}` after
+  # safe_load), not treated as "no frontmatter" (which rendered the two
+  # `---` lines as visible body text).
+  #
+  # Used in three places — Page (content files), RenderContext (layout
+  # files chaining via `layout:`), and Renderer (parent-layout lookup
+  # for the dep-mtime walker). Centralised here so the three callers
+  # stay in lockstep; previously the regex was duplicated and one copy
+  # had drifted (no body capture group), which made consolidation
+  # easy to put off.
+  FRONTMATTER_RE = /\A---\s*\n((?:.*?\n)?)---\s*\n(.*)/m.freeze
+end
+
+require_relative 'abqari/log'
+require_relative 'abqari/hooks'
+require_relative 'abqari/path_safe'
+require_relative 'abqari/http_safe'
+require_relative 'abqari/site_config'
+require_relative 'abqari/erbi_template'
+require_relative 'abqari/helpers'
+require_relative 'abqari/render_context'
+require_relative 'abqari/paginator'
+require_relative 'abqari/publication_normaliser'
+require_relative 'abqari/page'
+require_relative 'abqari/taxonomy_page'
+require_relative 'abqari/paginated_shard'
+require_relative 'abqari/asset_pipeline'
+require_relative 'abqari/bundle_assets'
+require_relative 'abqari/font_pipeline'
+require_relative 'abqari/theme_fonts'
+require_relative 'abqari/sitemap'
+require_relative 'abqari/feed'
+require_relative 'abqari/robots'
+require_relative 'abqari/headers_file'
+require_relative 'abqari/manifest'
+require_relative 'abqari/llms_txt'
+require_relative 'abqari/og_image_generator'
+require_relative 'abqari/security_txt'
+require_relative 'abqari/redirects'
+require_relative 'abqari/image_pipeline'
+require_relative 'abqari/minifier'
+require_relative 'abqari/search'
+require_relative 'abqari/syntax_highlighter'
+require_relative 'abqari/theme_bootstrap'
+require_relative 'abqari/speculation_rules_guard'
+require_relative 'abqari/plausible_script'
+require_relative 'abqari/visualizations'
+require_relative 'abqari/folio'
+require_relative 'abqari/indieweb'
+require_relative 'abqari/syndication'
+require_relative 'abqari/publisher_pages'
+require_relative 'abqari/related_index_page'
+require_relative 'abqari/site'
+require_relative 'abqari/audit'
+require_relative 'abqari/server'

data/themes/bootstrap/css/app.css

@@ -0,0 +1,97 @@
+/*
+  Bootstrap theme — project-level overrides.
+
+  The Bootstrap 5.3.8 distribution itself lives under
+  themes/bootstrap/public/css/bootstrap.min.css and is copied to
+  /css/bootstrap.min.css at build time. The head partial loads it
+  before this file, so any rule you write here wins on cascade.
+
+  This file is YOURS to edit — bump custom variables, add brand
+  colours, tweak component tokens. The vendored Bootstrap dist is
+  not edited. To upgrade Bootstrap, replace the files under
+  themes/bootstrap/public/.
+
+  Examples:
+
+    :root {
+      --bs-primary: #1a73e8;
+      --bs-link-color: var(--bs-primary);
+    }
+
+    .navbar-brand { font-weight: 700; }
+*/
+
+/* Primary nav — three flex children: brand, links, theme toggle.
+   `.nav__links { margin-left: auto }` pushes links + toggle to the
+   right edge. (Bootstrap theme skips _common.css, so we redeclare
+   the nav layout rules here.) */
+nav[aria-label="Primary"] {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 1rem;
+  margin-bottom: 1.5rem;
+}
+.nav__brand {
+  font-weight: 700;
+  text-decoration: none;
+  color: inherit;
+}
+.nav__brand:hover { opacity: 0.7; }
+.nav__links { margin-left: auto; }
+
+/* Active nav link — the one matching the current page (or section).
+   Bootstrap doesn't ship an active-link primitive for plain anchors;
+   we use the [aria-current="page"] selector emitted by the nav partial. */
+nav[aria-label="Primary"] [aria-current="page"] {
+  color: #111;
+  font-weight: 700;
+}
+@media (prefers-color-scheme: dark) {
+  nav[aria-label="Primary"] [aria-current="page"] { color: #f5f5f5; }
+}
+[data-theme="dark"]  nav[aria-label="Primary"] [aria-current="page"] { color: #f5f5f5; }
+[data-theme="light"] nav[aria-label="Primary"] [aria-current="page"] { color: #111; }
+
+/* Skip-link — visually hidden until focused. (Bootstrap doesn't ship
+   this primitive; the bootstrap theme also skips Abqari's _common.css
+   to avoid `.btn` / `.card` conflicts, so we redeclare it here.) */
+.skip-link {
+  position: absolute;
+  left: -10000px;
+  top: 0;
+  z-index: 999;
+  padding: 0.5rem 1rem;
+  background: #222;
+  color: #fff;
+  text-decoration: none;
+  border-bottom-right-radius: 0.25rem;
+}
+.skip-link:focus,
+.skip-link:focus-visible {
+  left: 0;
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+
+/* Footer bar — meta on the left, social icons on the right, same line.
+   Wraps to two rows on narrow viewports. Standardised across every
+   theme via the partial at app/views/partials/_footer.html.erb. */
+.footer-bar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+.footer-bar > p { margin: 0; }
+.footer-bar .footer-social { display: flex; gap: 0.5rem; align-items: center; }
+.footer-bar .footer-social a { display: inline-flex; align-items: center; }
+
+/* Breathing room around the footer — separation from page content
+   above (margin-top) and from the browser chrome below
+   (padding-bottom). */
+footer {
+  margin-top: 3rem;
+  padding-bottom: 2rem;
+}

data/themes/bootstrap/public/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2011-2025 The Bootstrap Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.