datalog-theme 0.6.0

data/lib/datalog/plugin_system/dependency_resolver.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Datalog
+  module PluginSystem
+    class DependencyResolver
+      attr_reader :plugins, :available_plugins
+
+      def initialize(plugins, options = {})
+        @plugins = Array(plugins).compact
+        @available_plugins = options.fetch(:available, {})
+        @graph = {}
+        @plugin_map = {}
+        @load_order = nil
+      end
+
+      def resolve
+        build_graph
+        validate_dependencies!
+        order = perform_topological_sort
+        @load_order = order.map { |identifier| @plugin_map[identifier] }
+      end
+
+      def load_order
+        @load_order ||= resolve
+      end
+
+      def dependency_graph
+        ensure_graph_built
+        @graph.transform_values { |meta| meta[:dependencies].dup }
+      end
+
+      def to_dot(order: load_order)
+        ensure_graph_built
+        ordered_ids = Array(order).map { |klass| klass.respond_to?(:id) ? klass.id : klass.to_s }
+        lines = []
+        lines << "digraph PluginDependencies {"
+        lines << "  rankdir=LR;"
+
+        @graph.each_key do |identifier|
+          klass = @plugin_map[identifier]
+          priority_label = klass&.respond_to?(:priority) ? klass.priority.to_s : "normal" # rubocop:disable Style/SafeNavigation
+          lines << %(  "#{identifier}" [label="#{identifier}\\npriority: #{priority_label}"];)
+        end
+
+        @graph.each do |identifier, meta|
+          meta[:dependencies].each do |dep|
+            lines << %(  "#{identifier}" -> "#{dep}";)
+          end
+        end
+
+        if ordered_ids.any?
+          order_comment = ordered_ids.each_with_index.map { |id, idx| "#{idx + 1}. #{id}" }.join(" | ")
+          lines << %(  // Load order: #{order_comment})
+        end
+
+        lines << "}"
+        lines.join("\n")
+      end
+
+      private
+
+      def build_graph
+        @plugin_map.clear
+        @graph.clear
+
+        plugins.each do |klass|
+          next unless klass.respond_to?(:id)
+
+          identifier = klass.id
+          @plugin_map[identifier] = klass
+          @graph[identifier] ||= { dependencies: Set.new, dependents: Set.new }
+
+          deps = klass.respond_to?(:dependencies) ? Array(klass.dependencies) : []
+          deps.each do |dep|
+            dep_id = dep.to_s
+            @graph[identifier][:dependencies] << dep_id
+            @graph[dep_id] ||= { dependencies: Set.new, dependents: Set.new }
+            @graph[dep_id][:dependents] << identifier
+          end
+        end
+      end
+
+      def validate_dependencies!
+        missing = {}
+
+        @graph.each do |identifier, meta|
+          meta[:dependencies].each do |dependency|
+            next if @plugin_map.key?(dependency)
+
+            missing[identifier] ||= []
+            missing[identifier] << dependency
+          end
+        end
+
+        return if missing.empty?
+
+        plugin_id, deps = missing.first
+        chain = deps.map { |dep| "#{plugin_id} → #{dep} (missing)" }
+        available = normalize_available
+        raise PluginDependencyError.missing(plugin_id: plugin_id, missing: deps, chain: chain, available: available)
+      end
+
+      def perform_topological_sort
+        indegree = Hash.new(0)
+        @graph.each_key { |identifier| indegree[identifier] ||= 0 }
+
+        @graph.each do |identifier, meta|
+          meta[:dependencies].each do |dependency|
+            next unless @plugin_map.key?(dependency)
+
+            indegree[identifier] += 1
+          end
+        end
+
+        queue = @plugin_map.values.select { |klass| indegree[klass.id].zero? }
+        queue.sort_by! { |klass| sort_signature(klass) }
+
+        sorted = []
+        until queue.empty?
+          current = queue.shift
+          sorted << current.id
+
+          dependents = Array(@graph.dig(current.id, :dependents))
+          dependents.each do |dependent|
+            next unless indegree.key?(dependent)
+
+            indegree[dependent] -= 1
+            next unless indegree[dependent].zero?
+
+            queue << @plugin_map[dependent]
+            queue.sort_by! { |klass| sort_signature(klass) }
+          end
+        end
+
+        if sorted.size != @plugin_map.size
+          raise PluginDependencyError.circular(cycle: build_cycle(sorted), available: normalize_available)
+        end
+
+        sorted
+      end
+
+      def sort_signature(klass)
+        priority_value = if klass.respond_to?(:priority_value)
+                           -klass.priority_value
+                         elsif klass.respond_to?(:priority) && klass.priority.respond_to?(:to_sym)
+                           -Datalog::PluginSystem::PRIORITY_LEVELS.fetch(klass.priority.to_sym, 0)
+                         else
+                           0
+                         end
+        [priority_value, klass.id.to_s]
+      end
+
+      def build_cycle(sorted_identifiers)
+        remaining = @plugin_map.keys - sorted_identifiers
+        return [] if remaining.empty?
+
+        visited = {}
+        stack = []
+
+        remaining.each do |identifier|
+          cycle = explore_cycle(identifier, visited, stack, remaining)
+          return format_cycle(cycle) if cycle
+        end
+
+        []
+      end
+
+      def explore_cycle(node, visited, stack, remaining)
+        state = visited[node]
+        return nil if state == :done
+
+        if state == :active
+          cycle_start = stack.index(node) || 0
+          return stack[cycle_start..] + [node]
+        end
+
+        visited[node] = :active
+        stack << node
+
+        Array(@graph.dig(node, :dependencies)).each do |dependency|
+          next unless @plugin_map.key?(dependency)
+          next unless remaining.include?(dependency)
+
+          cycle = explore_cycle(dependency, visited, stack, remaining)
+          return cycle if cycle
+        end
+
+        stack.pop
+        visited[node] = :done
+        nil
+      end
+
+      def format_cycle(nodes)
+        return [] unless Array(nodes).any?
+
+        edges = []
+        nodes.each_cons(2) do |from, to|
+          edges << "#{from} → #{to}"
+        end
+        edges << "#{nodes.last} → #{nodes.first}" if nodes.length > 1
+        edges
+      end
+
+      def ensure_graph_built
+        build_graph if @graph.empty? && plugins.any?
+      end
+
+      def normalize_available
+        if available_plugins.respond_to?(:keys)
+          available_plugins.keys
+        elsif available_plugins.respond_to?(:map)
+          available_plugins.map do |value|
+            value.respond_to?(:id) ? value.id : value
+          end
+        else
+          Array(available_plugins)
+        end
+      end
+    end
+  end
+end

data/lib/datalog/plugin_system.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "jekyll"
+
+module Datalog
+  module PluginSystem
+    HOOKS = %i[before_render after_post_process custom_liquid_tags search_indexing].freeze
+
+    PRIORITY_LEVELS = {
+      highest: 40,
+      high: 30,
+      normal: 20,
+      low: 10,
+      lowest: 0
+    }.freeze
+
+    class PluginDependencyError < StandardError
+      attr_reader :plugin_id
+
+      def initialize(message, plugin_id: nil)
+        super(message)
+        @plugin_id = plugin_id
+      end
+
+      def self.missing(plugin_id:, missing:, chain:, available: [])
+        missing_list = Array(missing)
+        message = "Cannot load '#{plugin_id}'\n"
+        descriptor = missing_list.size > 1 ? "Missing dependencies" : "Missing dependency"
+        message << "  #{descriptor}: #{missing_list.map { |id| "'#{id}'" }.join(', ')}\n"
+
+        if Array(chain).any?
+          message << "\n  Dependency chain:\n"
+          Array(chain).each do |step|
+            message << "    #{step}\n"
+          end
+        end
+
+        message << "\n  Available plugins: #{Array(available).map(&:to_s).sort.join(', ')}\n" if Array(available).any?
+
+        fix_line = if missing_list.size == 1
+                     "  To fix: Add '#{missing_list.first}' to enabled plugins in _config.yml"
+                   else
+                     joined = missing_list.map { |id| "'#{id}'" }.join(", ")
+                     "  To fix: Add #{joined} to enabled plugins in _config.yml"
+                   end
+        message << "\n" << fix_line
+
+        new(message, plugin_id: plugin_id)
+      end
+
+      def self.circular(cycle:, available: [])
+        message = String.new("Circular dependency detected\n")
+        if Array(cycle).any?
+          message << "\n  Cycle:\n"
+          Array(cycle).each do |step|
+            message << "    #{step}\n"
+          end
+        end
+
+        message << "\n  Available plugins: #{Array(available).map(&:to_s).sort.join(', ')}" if Array(available).any?
+
+        new(message)
+      end
+    end
+
+    class << self
+      attr_accessor :active_plugins, :site
+
+      def available_plugins
+        @available_plugins ||= {}
+      end
+
+      def register(klass)
+        identifier = klass.id
+        return unless identifier
+
+        available_plugins[identifier] = klass
+      end
+
+      def activate!(site, plugin_instances)
+        self.site = site
+        self.active_plugins = plugin_instances
+      end
+
+      def plugin(identifier)
+        Array(active_plugins).find { |instance| instance.id == identifier }
+      end
+
+      def active_plugin_ids
+        Array(active_plugins).map(&:id)
+      end
+
+      def run_hook(hook, *args)
+        return unless HOOKS.include?(hook)
+
+        Array(active_plugins).each do |plugin|
+          next unless plugin.respond_to?(hook)
+
+          plugin.public_send(hook, *args)
+        rescue StandardError => e
+          Jekyll.logger.warn("datalog plugin", "#{plugin.id} failed during #{hook}: #{e.message}")
+        end
+      end
+
+      def collect_hook(hook, *args)
+        return {} unless HOOKS.include?(hook)
+
+        Array(active_plugins).each_with_object({}) do |plugin, acc|
+          next unless plugin.respond_to?(hook)
+
+          result = plugin.public_send(hook, *args)
+          next unless result.is_a?(Hash)
+
+          acc.replace(deep_merge(acc, result))
+        rescue StandardError => e
+          Jekyll.logger.warn("datalog plugin", "#{plugin.id} failed during #{hook}: #{e.message}")
+        end
+      end
+
+      private
+
+      def deep_merge(left, right)
+        left.merge(right) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          elsif old_val.is_a?(Array) || new_val.is_a?(Array)
+            Array(old_val) + Array(new_val)
+          else
+            new_val
+          end
+        end
+      end
+    end
+
+    class Plugin
+      class << self
+        attr_writer :identifier
+
+        def depends_on(*plugin_ids)
+          return dependencies if plugin_ids.empty?
+
+          normalized = plugin_ids.flatten.compact.map(&:to_s).reject(&:empty?)
+          @dependencies = (dependencies + normalized).uniq
+        end
+
+        def dependencies
+          @dependencies ||= []
+        end
+
+        def priority(value = nil)
+          if value.nil?
+            @priority ||= :normal
+          else
+            symbol = value.to_sym
+            unless PRIORITY_LEVELS.key?(symbol)
+              raise ArgumentError, "Invalid plugin priority '#{value}'. Allowed: #{PRIORITY_LEVELS.keys.join(', ')}"
+            end
+
+            @priority = symbol
+          end
+        end
+
+        def priority_value
+          PRIORITY_LEVELS.fetch(priority, PRIORITY_LEVELS[:normal])
+        end
+
+        def id(value = nil)
+          if value
+            new_id = value.to_s
+            registry = Datalog::PluginSystem.available_plugins
+            previous_id = @identifier || default_identifier
+
+            registry.delete(previous_id) if previous_id && registry[previous_id] == self
+
+            @identifier = new_id
+            registry[new_id] = self
+          else
+            @identifier ||= default_identifier
+          end
+        end
+
+        def inherited(subclass)
+          super
+          Datalog::PluginSystem.register(subclass)
+        end
+
+        private
+
+        def default_identifier
+          raw = name&.split("::")&.last
+          raw ||= "plugin-#{object_id}"
+
+          raw.gsub(/([a-z\d])([A-Z])/, "\\1-\\2")
+             .tr("_", "-")
+             .downcase
+        end
+      end
+
+      attr_reader :site, :config
+
+      def initialize(site, config = {})
+        @site = site
+        @config = (config || {}).transform_keys(&:to_s)
+      end
+
+      def id
+        self.class.id
+      end
+
+      def dependencies
+        self.class.dependencies
+      end
+
+      def priority
+        self.class.priority
+      end
+
+      def logger
+        @logger ||= Jekyll.logger
+      end
+
+      def before_render(_document, _payload = nil); end
+
+      def after_post_process(_document); end
+
+      def custom_liquid_tags
+        {}
+      end
+
+      def search_indexing(_document)
+        {}
+      end
+    end
+  end
+end
+
+require_relative "plugin_system/dependency_resolver"

data/lib/datalog/plugins/citations.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Datalog
+  module Plugins
+    class Citations < Datalog::PluginSystem::Plugin
+      id "datalog-citations"
+      depends_on "datalog-search"
+      priority :high
+
+      class CiteTag < Liquid::Tag
+        def initialize(tag_name, markup, tokens)
+          super
+          args = Shellwords.split(markup)
+          @citation_key = args.shift
+          @label = args.shift
+        end
+
+        def render(context)
+          plugin = Datalog::PluginSystem.plugin("datalog-citations")
+          return missing_placeholder unless plugin
+
+          plugin.render_citation(context, @citation_key, @label)
+        end
+
+        private
+
+        def missing_placeholder
+          "<span class=\"datalog-citation datalog-citation--missing\">[citation]</span>"
+        end
+      end
+
+      class BibliographyTag < Liquid::Tag
+        def render(context)
+          plugin = Datalog::PluginSystem.plugin("datalog-citations")
+          return "" unless plugin
+
+          plugin.render_bibliography(context)
+        end
+      end
+
+      def initialize(site, config = {})
+        super
+        @state = {}
+      end
+
+      def before_render(document, _payload = nil)
+        citations = collect_citations(document)
+        state = ensure_state(document)
+        state[:lookup] = citations
+        state[:order] = []
+        document.data["datalog_citations"] = citations
+        document.data["datalog_bibliography"] = citations.values
+        document.data["datalog_citation_state"] = state[:key]
+        return unless config["bibliography_title"]
+
+        document.data["datalog_bibliography_title"] = config["bibliography_title"]
+      end
+
+      def custom_liquid_tags
+        {
+          "datalog_cite" => CiteTag,
+          "datalog_bibliography" => BibliographyTag
+        }
+      end
+
+      def search_indexing(document)
+        state = resolve_state(document)
+        return {} unless state && state[:lookup]&.any?
+
+        {
+          "citations" => {
+            "count" => state[:lookup].size,
+            "keys" => state[:lookup].keys.sort
+          }
+        }
+      end
+
+      def render_citation(context, key, label)
+        return missing_markup unless key
+
+        state = state_from_context(context)
+        return missing_markup unless state
+
+        normalized_key = key.to_s
+        entry = state[:lookup][normalized_key]
+        return missing_markup unless entry
+
+        state[:order] << normalized_key unless state[:order].include?(normalized_key)
+        index = state[:order].index(normalized_key) + 1
+        text = label || entry[:label] || "[#{index}]"
+        text = text.gsub("%{n}", index.to_s)
+
+        if entry[:url]
+          %(<a class="datalog-citation" href="#{entry[:url]}" rel="noopener" data-citation="#{normalized_key}">#{text}</a>)
+        else
+          %(<span class="datalog-citation" data-citation="#{normalized_key}">#{text}</span>)
+        end
+      end
+
+      def render_bibliography(context)
+        state = state_from_context(context)
+        return "" unless state && state[:lookup]&.any?
+
+        entries = state[:order].map { |key| state[:lookup][key] }.compact
+        entries = state[:lookup].values if entries.empty?
+
+        items = entries.each_with_index.map do |entry, idx|
+          anchor = entry[:id] || "citation-#{idx + 1}"
+          %(<li id="cite-#{anchor}">#{entry[:formatted]}</li>)
+        end
+
+        %(<ol class="datalog-bibliography">#{items.join}</ol>)
+      end
+
+      private
+
+      def collect_citations(document)
+        entries = Array(document.data["citations"] || document.data["references"])
+        global = Array(site.data.dig("citations", document.data["citation_group"]))
+        entries += global if global.any?
+
+        entries.each_with_object({}) do |entry, acc|
+          normalized = normalize_entry(entry)
+          next unless normalized[:id]
+
+          acc[normalized[:id]] = normalized
+        end
+      end
+
+      def normalize_entry(entry)
+        case entry
+        when String
+          identifier = entry.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")
+          { id: identifier, title: entry, formatted: entry }
+        when Hash
+          normalized = entry.transform_keys(&:to_sym)
+          normalized[:id] = normalized[:id].to_s if normalized[:id]
+          normalized[:formatted] ||= build_formatted_entry(normalized)
+          normalized
+        else
+          {}
+        end
+      end
+
+      def build_formatted_entry(entry)
+        authors = Array(entry[:authors] || entry[:author]).join(", ")
+        year = entry[:year]
+        title = entry[:title]
+        container = entry[:journal] || entry[:conference] || entry[:publisher]
+        segments = []
+        segments << authors unless authors.empty?
+        segments << "(#{year})" if year
+        segments << "<em>#{title}</em>" if title
+        segments << container if container
+        segments << entry[:url] if entry[:url] && !entry[:url].empty?
+        segments.compact.join(". ")
+      end
+
+      def ensure_state(document)
+        key = document.relative_path || document.path
+        @state[key] = { key: key }.merge(@state[key] || {})
+      end
+
+      def resolve_state(document)
+        key = document.data["datalog_citation_state"] || document.relative_path || document.path
+        @state[key]
+      end
+
+      def state_from_context(context)
+        page = context.registers[:page] || {}
+        key = page["datalog_citation_state"]
+        @state[key]
+      end
+
+      def missing_markup
+        "<span class=\"datalog-citation datalog-citation--missing\">[citation]</span>"
+      end
+    end
+  end
+end