datalog-theme 0.6.0

data/_plugins/analytics_dashboard.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "time"
+require "stringio"
+require "fileutils"
+
+module Datalog
+  module Analytics
+    GA_SCOPE = "https://www.googleapis.com/auth/analytics.readonly"
+    CACHE_RELATIVE_PATH = ".jekyll-cache/datalog-analytics.json"
+    CACHE_TTL = 24 * 60 * 60
+    HTTP_TIMEOUTS = { open: 5, read: 15, write: 15 }.freeze
+    HTTP_MAX_RETRIES = 2
+    RETRYABLE_ERRORS = [
+      Timeout::Error,
+      Errno::ECONNRESET,
+      Errno::ETIMEDOUT,
+      SocketError,
+      Net::OpenTimeout,
+      Net::ReadTimeout
+    ].freeze
+
+    module_function
+
+    def fetch(site)
+      cache_path = cache_path_for(site)
+      cached = read_cache(cache_path)
+      return cached if fresh?(cached)
+
+      data = query_analytics(site)
+      data["fetched_at"] = Time.now.utc.iso8601
+      write_cache(cache_path, data)
+      data
+    rescue StandardError => e
+      Jekyll.logger.warn("Analytics", "Falling back to cached analytics data: #{e.message}")
+      cached || fallback_payload("error", e.message)
+    end
+
+    def cache_path_for(site)
+      File.join(site.source, CACHE_RELATIVE_PATH)
+    end
+
+    def fresh?(payload)
+      return false unless payload.is_a?(Hash)
+
+      fetched_at = payload["fetched_at"]
+      return false if fetched_at.to_s.empty?
+
+      Time.parse(fetched_at) > Time.now - CACHE_TTL
+    rescue ArgumentError
+      false
+    end
+
+    def read_cache(path)
+      return unless File.exist?(path)
+
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_cache(path, payload)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.pretty_generate(payload))
+    rescue StandardError => e
+      Jekyll.logger.warn("Analytics", "Unable to persist analytics cache: #{e.message}")
+    end
+
+    def query_analytics(site)
+      config = site.config.fetch("analytics", {})
+      property_id = ENV["GA4_PROPERTY_ID"] || config["ga4_property_id"]
+      credentials_json = credentials_payload(config)
+
+      unless property_id && !property_id.empty?
+        return fallback_payload("missing_configuration", "Set GA4_PROPERTY_ID to enable analytics dashboards.")
+      end
+
+      unless credentials_json
+        return fallback_payload("missing_credentials",
+                                "Provide GA4 service account credentials to query the Analytics API.")
+      end
+
+      token = fetch_access_token(credentials_json)
+
+      requests = build_requests
+      results = {}
+      requests.each do |key, body|
+        results[key] = run_report(property_id, token, body)
+      end
+
+      enrich_with_monthly_reports!(results)
+      inject_scholar_metrics!(results, site)
+      results["status"] = "ok"
+      results
+    rescue LoadError => e
+      fallback_payload("missing_dependency", "Install googleauth to enable GA4 integration: #{e.message}")
+    rescue StandardError => e
+      fallback_payload("error", e.message)
+    end
+
+    def credentials_payload(config)
+      json = ENV.fetch("GA4_CREDENTIALS_JSON", nil)
+      return json unless json.to_s.strip.empty?
+
+      path = ENV["GA4_CREDENTIALS_PATH"] || config["ga4_credentials_path"]
+      return File.read(path) if path && File.exist?(path)
+
+      config_json = config["ga4_credentials_json"]
+      return config_json unless config_json.to_s.strip.empty?
+
+      nil
+    end
+
+    def fetch_access_token(credentials_json)
+      require "googleauth"
+
+      credentials = Google::Auth::ServiceAccountCredentials.make_creds(
+        scope: GA_SCOPE,
+        json_key_io: StringIO.new(credentials_json)
+      )
+      credentials.fetch_access_token!
+      credentials.access_token
+    end
+
+    def build_requests
+      {
+        "top_posts" => {
+          "dimensions" => [{ "name" => "pagePath" }],
+          "metrics" => [
+            { "name" => "screenPageViews" },
+            { "name" => "userEngagementDuration" }
+          ],
+          "dateRanges" => [{ "startDate" => "28daysAgo", "endDate" => "today" }],
+          "limit" => 10,
+          "orderBys" => [{ "metric" => { "metricName" => "screenPageViews" }, "desc" => true }]
+        },
+        "search_terms" => {
+          "dimensions" => [{ "name" => "searchTerm" }],
+          "metrics" => [{ "name" => "sessions" }],
+          "dateRanges" => [{ "startDate" => "28daysAgo", "endDate" => "today" }],
+          "limit" => 10,
+          "orderBys" => [{ "metric" => { "metricName" => "sessions" }, "desc" => true }]
+        },
+        "visitor_trends" => {
+          "dimensions" => [{ "name" => "date" }],
+          "metrics" => [
+            { "name" => "totalUsers" },
+            { "name" => "newUsers" },
+            { "name" => "sessions" },
+            { "name" => "screenPageViews" }
+          ],
+          "dateRanges" => [{ "startDate" => "90daysAgo", "endDate" => "today" }],
+          "orderBys" => [{ "dimension" => { "dimensionName" => "date" } }]
+        },
+        "engagement_by_page" => {
+          "dimensions" => [{ "name" => "pagePath" }],
+          "metrics" => [
+            { "name" => "screenPageViews" },
+            { "name" => "averageSessionDuration" },
+            { "name" => "engagedSessions" }
+          ],
+          "dateRanges" => [{ "startDate" => "28daysAgo", "endDate" => "today" }],
+          "limit" => 20,
+          "orderBys" => [{ "metric" => { "metricName" => "engagedSessions" }, "desc" => true }]
+        },
+        "key_events" => {
+          "dimensions" => [{ "name" => "eventName" }],
+          "metrics" => [{ "name" => "eventCount" }],
+          "dimensionFilter" => {
+            "filter" => {
+              "inListFilter" => {
+                "dimensionName" => "eventName",
+                "values" => %w[notebook_download demo_launch]
+              }
+            }
+          },
+          "dateRanges" => [{ "startDate" => "28daysAgo", "endDate" => "today" }],
+          "limit" => 10,
+          "orderBys" => [{ "metric" => { "metricName" => "eventCount" }, "desc" => true }]
+        }
+      }
+    end
+
+    def run_report(property_id, token, body)
+      uri = URI("https://analyticsdata.googleapis.com/v1beta/properties/#{property_id}:runReport")
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{token}"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.dump(body)
+
+      response = perform_http_request(uri) { |http| http.request(request) }
+
+      raise "GA4 API error: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body)
+    end
+
+    def enrich_with_monthly_reports!(results)
+      trend_rows = extract_rows(results.fetch("visitor_trends", {}))
+      monthly = Hash.new do |hash, key|
+        hash[key] = {
+          "total_users" => 0,
+          "new_users" => 0,
+          "sessions" => 0,
+          "page_views" => 0
+        }
+      end
+
+      trend_rows.each do |row|
+        month = row.dig("dimensionValues", 0, "value")&.to_s&.slice(0, 6)
+        next unless month
+
+        data = monthly[month]
+        metrics = row["metricValues"] || []
+        data["total_users"] += metrics.fetch(0, {})["value"].to_f
+        data["new_users"] += metrics.fetch(1, {})["value"].to_f
+        data["sessions"] += metrics.fetch(2, {})["value"].to_f
+        data["page_views"] += metrics.fetch(3, {})["value"].to_f
+      end
+
+      reports = monthly.keys.sort.reverse.map do |month|
+        {
+          "month" => format_month(month),
+          "total_users" => monthly[month]["total_users"].round,
+          "new_users" => monthly[month]["new_users"].round,
+          "sessions" => monthly[month]["sessions"].round,
+          "page_views" => monthly[month]["page_views"].round
+        }
+      end
+
+      results["monthly_reports"] = reports
+    end
+
+    def format_month(key)
+      return key unless key && key.length == 6
+
+      year = key[0, 4]
+      month = key[4, 2]
+      "#{year}-#{month}"
+    end
+
+    def inject_scholar_metrics!(results, site)
+      academic = site.data["academic"] || {}
+      citations = academic.fetch("citations", {})
+      metrics = citations.fetch("metrics", {})
+      results["scholar"] = {
+        "total" => metrics["total"],
+        "h_index" => metrics["h_index"],
+        "i10_index" => metrics["i10_index"],
+        "since_2019" => metrics.fetch("since_2019", {}),
+        "yearly_totals" => citations.fetch("yearly_totals", {})
+      }
+      results
+    end
+
+    def extract_rows(response)
+      return [] unless response.is_a?(Hash)
+
+      response.fetch("rows", [])
+    end
+
+    def fallback_payload(status, message)
+      {
+        "status" => status,
+        "message" => message,
+        "top_posts" => { "rows" => [] },
+        "search_terms" => { "rows" => [] },
+        "visitor_trends" => { "rows" => [] },
+        "engagement_by_page" => { "rows" => [] },
+        "key_events" => { "rows" => [] },
+        "monthly_reports" => [],
+        "scholar" => {}
+      }
+    end
+
+    def perform_http_request(uri)
+      attempts = 0
+      begin
+        attempts += 1
+        Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+          apply_timeouts(http)
+          yield(http)
+        end
+      rescue *RETRYABLE_ERRORS => e
+        raise if attempts > HTTP_MAX_RETRIES
+
+        Jekyll.logger.warn(
+          "Analytics",
+          "Retrying GA4 request (attempt #{attempts}): #{e.class}: #{e.message}"
+        )
+        sleep(0.25 * attempts)
+        retry
+      end
+    end
+
+    def apply_timeouts(http)
+      http.open_timeout = HTTP_TIMEOUTS[:open]
+      http.read_timeout = HTTP_TIMEOUTS[:read]
+      return unless http.respond_to?(:write_timeout=) && HTTP_TIMEOUTS[:write]
+
+      http.write_timeout = HTTP_TIMEOUTS[:write]
+    end
+  end
+
+  class AnalyticsDashboardGenerator < Jekyll::Generator
+    safe true
+    priority :low
+
+    def generate(site)
+      site.data["analytics_dashboard"] = Analytics.fetch(site)
+    end
+  end
+end

data/_plugins/config_validator.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Datalog
+  class ConfigValidator < Jekyll::Generator
+    safe true
+    priority :highest
+
+    DOCUMENTATION_BASE_URL = "https://datalog-theme.github.io/docs/configuration-reference"
+
+    SCHEMA = {
+      title: { type: :string, required: true },
+      url: { type: :string, required: true, format: :url },
+      author: {
+        type: :hash,
+        required: true,
+        schema: {
+          name: { type: :string, required: true },
+          email: { type: :string, format: :email }
+        }
+      },
+      markdown: { type: :string, enum: %w[kramdown commonmark] },
+      highlighter: { type: :string, enum: %w[rouge pygments] },
+      permalink: { type: :string },
+      paginate: { type: :integer },
+      timezone: { type: :string },
+      collections: { type: :hash },
+      plugins: { type: :array },
+      features: {
+        type: :hash,
+        schema: {
+          mathjax: { type: :boolean },
+          search: { type: :boolean },
+          dark_mode_toggle: { type: :boolean },
+          notebook_support: { type: :boolean },
+          portfolio: { type: :boolean },
+          datasets: { type: :boolean }
+        }
+      },
+      notebooks: {
+        type: :hash,
+        schema: {
+          enabled: { type: :boolean },
+          source: { type: :string },
+          output_dir: { type: :string }
+        }
+      },
+      seo: {
+        type: :hash,
+        schema: {
+          type: { type: :string },
+          name: { type: :string }
+        }
+      },
+      sass: {
+        type: :hash,
+        schema: {
+          style: { type: :string, enum: %w[compressed expanded] }
+        }
+      },
+      theme_options: {
+        type: :hash,
+        schema: {
+          math: {
+            type: :hash,
+            schema: {
+              engine: { type: :string, enum: %w[mathjax katex] },
+              enabled: { type: :boolean }
+            }
+          },
+          syntax_highlighting: {
+            type: :hash,
+            schema: {
+              cdn: { type: :string }
+            }
+          }
+        }
+      }
+    }.freeze
+
+    DEPRECATED_KEYS = {
+      "math_engine" => {
+        replacement: "theme_options.math.engine",
+        message: "'math_engine' has moved under theme_options.math.engine.",
+        auto_migrate: true
+      }
+    }.freeze
+
+    COMMON_SUGGESTIONS = {
+      %w[theme_options math engine] => {
+        "latex" => "mathjax",
+        "mathjax3" => "mathjax"
+      }
+    }.freeze
+
+    class Validator
+      attr_reader :errors, :warnings
+
+      def initialize(config)
+        @config = config
+        @errors = []
+        @warnings = []
+      end
+
+      def run
+        @errors.clear
+        @warnings.clear
+
+        apply_deprecated_migrations
+        validate_schema(@config, SCHEMA)
+
+        self
+      end
+
+      def formatted_errors
+        return "" if errors.empty?
+
+        errors.map { |error| format_error(error) }.join("\n\n") +
+          "\n\nBuild failed. Fix the above error in _config.yml and try again."
+      end
+
+      private
+
+      def apply_deprecated_migrations
+        DEPRECATED_KEYS.each do |path, metadata|
+          key_path = normalize_path(path)
+          value = dig_value(@config, key_path)
+          next if value.nil?
+
+          if metadata[:auto_migrate] && metadata[:replacement]
+            target_path = normalize_path(metadata[:replacement])
+            existing = dig_value(@config, target_path)
+            if existing.nil?
+              assign_value(@config, target_path, value)
+              @warnings << "Deprecated config key '#{path}' detected. Automatically migrated to '#{metadata[:replacement]}'."
+            else
+              @warnings << "Deprecated config key '#{path}' detected. Value already set at '#{metadata[:replacement]}', skipping migration."
+            end
+            remove_value(@config, key_path)
+          else
+            @warnings << "Deprecated config key '#{path}' detected. #{metadata[:message]}"
+          end
+        end
+      end
+
+      def validate_schema(data, schema, path = [])
+        schema.each do |key, rules|
+          key_path = path + [key.to_s]
+          present, value = fetch_value(data, key)
+
+          unless present
+            errors << build_missing_error(key_path) if rules[:required]
+            next
+          end
+
+          if value.nil?
+            errors << build_missing_error(key_path) if rules[:required]
+            next
+          end
+
+          validate_type(key_path, value, rules)
+
+          next unless rules[:schema] && value.is_a?(Hash)
+
+          validate_schema(value, rules[:schema], key_path)
+        end
+      end
+
+      def validate_type(path, value, rules)
+        expected_type = rules[:type]
+        if expected_type && !type_valid?(value, expected_type)
+          errors << build_type_error(path, expected_type, value)
+          return
+        end
+
+        if rules[:enum]
+          enum_values = Array(rules[:enum])
+          unless enum_values.include?(value)
+            errors << build_enum_error(path, enum_values, value)
+            return
+          end
+        end
+
+        case rules[:format]
+        when :url
+          errors << build_format_error(path, "a valid URL", value) unless url_valid?(value)
+        when :email
+          errors << build_format_error(path, "a valid email address", value) unless email_valid?(value)
+        end
+      end
+
+      def fetch_value(data, key)
+        return [false, nil] unless data.is_a?(Hash)
+
+        key_str = key.to_s
+        if data.key?(key_str)
+          [true, data[key_str]]
+        elsif data.key?(key.to_sym)
+          [true, data[key.to_sym]]
+        else
+          [false, nil]
+        end
+      end
+
+      def type_valid?(value, expected_type)
+        case expected_type
+        when :string
+          value.is_a?(String)
+        when :integer
+          value.is_a?(Integer)
+        when :boolean
+          [true, false].include?(value)
+        when :array
+          value.is_a?(Array)
+        when :hash
+          value.is_a?(Hash)
+        else
+          true
+        end
+      end
+
+      def url_valid?(value)
+        return false unless value.is_a?(String)
+
+        uri = URI.parse(value)
+        uri.is_a?(URI::HTTP) && !uri.host.nil?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def email_valid?(value)
+        return false unless value.is_a?(String)
+
+        /\A[^\s@]+@[^\s@]+\.[^\s@]+\z/.match?(value)
+      end
+
+      def build_missing_error(path)
+        identifier = path.join(".")
+        {
+          headline: "Missing required configuration '#{identifier}'",
+          path: path,
+          expected: "Value required",
+          actual: "nil",
+          doc_url: documentation_url(path)
+        }
+      end
+
+      def build_type_error(path, expected_type, value)
+        identifier = path.join(".")
+        {
+          headline: "Invalid type for '#{identifier}'",
+          path: path,
+          expected: human_type(expected_type),
+          actual: value.inspect,
+          doc_url: documentation_url(path)
+        }
+      end
+
+      def build_enum_error(path, enum_values, value)
+        identifier = path.join(".")
+        suggestion = suggestion_for(path, value)
+        {
+          headline: "Invalid value for '#{identifier}'",
+          path: path,
+          expected: enum_values.map { |v| "\"#{v}\"" }.join(" or "),
+          actual: value.inspect,
+          suggestion: suggestion,
+          doc_url: documentation_url(path)
+        }
+      end
+
+      def build_format_error(path, expectation, value)
+        identifier = path.join(".")
+        {
+          headline: "Invalid value for '#{identifier}'",
+          path: path,
+          expected: expectation,
+          actual: value.inspect,
+          doc_url: documentation_url(path)
+        }
+      end
+
+      def suggestion_for(path, value)
+        map = COMMON_SUGGESTIONS[path]
+        return unless map
+
+        suggestion = map[value.to_s.downcase]
+        return unless suggestion
+
+        "Did you mean \"#{suggestion}\"?"
+      end
+
+      def format_error(error)
+        lines = []
+        lines << "Configuration Error: #{error[:headline]}"
+        lines << ""
+        lines << "  Path: #{error[:path].join(' → ')}"
+        lines << "  Expected: #{error[:expected]}" if error[:expected]
+        lines << "  Received: #{error[:actual]}" if error[:actual]
+        lines << ""
+        lines << "  #{error[:suggestion]}" if error[:suggestion]
+        lines << "  Documentation: #{error[:doc_url]}"
+        lines.compact!
+        lines.join("\n")
+      end
+
+      def documentation_url(path)
+        anchor = path.map { |segment| segment.gsub(/[^a-z0-9]+/i, "-") }.join("-").downcase
+        "#{DOCUMENTATION_BASE_URL}##{anchor}"
+      end
+
+      def human_type(type)
+        case type
+        when :string then "a String"
+        when :integer then "an Integer"
+        when :boolean then "a Boolean"
+        when :array then "an Array"
+        when :hash then "a Hash"
+        else
+          type.to_s
+        end
+      end
+
+      def normalize_path(path)
+        case path
+        when String
+          path.split(".")
+        when Array
+          path.map(&:to_s)
+        else
+          [path.to_s]
+        end
+      end
+
+      def dig_value(data, path)
+        return nil unless data.is_a?(Hash)
+
+        head, *tail = path
+        return nil if head.nil?
+
+        value = data[head] || data[head.to_sym]
+        return value if tail.empty?
+
+        dig_value(value, tail)
+      end
+
+      def assign_value(data, path, value)
+        head, *tail = path
+        key_str = head.to_s
+        if tail.empty?
+          data[key_str] = value
+          return
+        end
+
+        data[key_str] = {} unless data[key_str].is_a?(Hash)
+        assign_value(data[key_str], tail, value)
+      end
+
+      def remove_value(data, path)
+        return unless data.is_a?(Hash)
+
+        head, *tail = path
+        key_str = head.to_s
+        if tail.empty?
+          data.delete(key_str)
+          data.delete(head.to_sym)
+          return
+        end
+
+        child = data[key_str] || data[head.to_sym]
+        return unless child.is_a?(Hash)
+
+        remove_value(child, tail)
+      end
+    end
+
+    def generate(site)
+      validator = Validator.new(site.config)
+      validator.run
+
+      validator.warnings.each do |warning|
+        logger.warn("config", warning)
+      end
+
+      return if validator.errors.empty?
+
+      raise Jekyll::Errors::FatalException, validator.formatted_errors
+    end
+
+    private
+
+    def logger
+      Jekyll.logger
+    end
+  end
+end