perron 0.17.0 → 0.18.0

data/lib/perron/data_source/item.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Perron
+  class DataSource < SimpleDelegator
+    class Item
+      def initialize(attributes, identifier:)
+        @attributes = attributes.transform_keys(&:to_sym)
+        @identifier = identifier
+      end
+
+      def [](key) = @attributes[key.to_sym]
+
+      def association_value(key) = self[key]
+
+      def to_partial_path
+        @to_partial_path ||= begin
+          identifier = @identifier.to_s
+          collection = File.extname(identifier).present? ? File.basename(identifier, ".*") : identifier
+          element = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.singularize(File.basename(collection)))
+
+          File.join("content", collection, element)
+        end
+      end
+
+      def method_missing(method_name, *arguments, &block)
+        return super if !@attributes.key?(method_name) || arguments.any? || block
+
+        @attributes[method_name]
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @attributes.key?(method_name) || super
+      end
+    end
+    private_constant :Item
+  end
+end

data/lib/perron/{data → data_source}/proxy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Perron
-  class Data
+  class DataSource
     class Proxy
       include Enumerable
 

data/lib/perron/data_source.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "csv"
+
+require "perron/data_source/class_methods"
+require "perron/data_source/item"
+require "perron/data_source/helper_context"
+
+module Perron
+  class DataSource < SimpleDelegator
+    include Enumerable
+
+    include Perron::DataSource::ClassMethods
+
+    def initialize(identifier)
+      @identifier = identifier
+      @file_path = self.class.path_for!(identifier)
+      @records = records
+
+      super(records)
+    end
+
+    def each(&block) = @records.each(&block)
+
+    def count = @records.count
+
+    def first(n = nil)
+      n ? @records.first(n) : @records.first
+    end
+
+    def last = @records.last
+
+    def [](index) = @records[index]
+
+    def size = @records.size
+    alias_method :length, :size
+
+    private
+
+    PARSER_METHODS = {
+      ".yml" => :parse_yaml, ".yaml" => :parse_yaml,
+      ".json" => :parse_json, ".csv" => :parse_csv
+    }.freeze
+    SUPPORTED_EXTENSIONS = PARSER_METHODS.keys
+
+    def records
+      content = rendered_from(@file_path)
+      data = parsed_from(content, @file_path)
+
+      unless data.is_a?(Array)
+        raise Errors::DataParseError, "Data in `#{@file_path}` must be an array of objects."
+      end
+
+      data.map.with_index do |item, index|
+        unless item.is_a?(Hash)
+          raise Errors::DataParseError, "Item at index #{index} in `#{@file_path}` must be a hash/object, got #{item.class}"
+        end
+
+        Item.new(item, identifier: @identifier)
+      end
+    end
+    # def records
+    #   content = rendered_from(@file_path)
+    #   data = parsed_from(content, @file_path)
+
+    #   unless data.is_a?(Array)
+    #     raise Errors::DataParseError, "Data in `#{@file_path}` must be an array of objects."
+    #   end
+
+    #   data.map { Item.new(it, identifier: @identifier) }
+    # end
+
+    def rendered_from(path)
+      raw_content = File.read(path)
+
+      render_erb(raw_content)
+    rescue NameError, ArgumentError, SyntaxError => error
+      raise Errors::DataParseError, "Failed to render ERB in `#{path}`: (#{error.class}) #{error.message}"
+    end
+
+    def parsed_from(content, path)
+      extension = File.extname(path)
+      parser_method = PARSER_METHODS.fetch(extension) do
+        raise Errors::UnsupportedDataFormatError, "Unsupported data format: #{extension}. Supported formats: #{SUPPORTED_EXTENSIONS.join(", ")}"
+      end
+
+      send(parser_method, content, path)
+    end
+    # def parsed_from(content, path)
+    #   extension = File.extname(path)
+    #   parser_method = PARSER_METHODS.fetch(extension) do
+    #     raise Errors::UnsupportedDataFormatError, "Unsupported data format: #{extension}"
+    #   end
+
+    #   send(parser_method, content)
+    # rescue Psych::SyntaxError, JSON::ParserError, CSV::MalformedCSVError => error
+    #   raise Errors::DataParseError, "Failed to parse data format in `#{path}`: (#{error.class}) #{error.message}"
+    # end
+
+    def render_erb(content) = ERB.new(content).result(HelperContext.instance.get_binding)
+
+    def parse_yaml(content, path)
+      YAML.safe_load(content, permitted_classes: [Symbol, Time], aliases: true)
+    rescue Psych::SyntaxError => error
+      line_info = error.line ? " at line #{error.line}" : ""
+      column_info = error.column ? ", column #{error.column}" : ""
+
+      raise Errors::DataParseError, "Invalid YAML syntax in `#{path}`#{line_info}#{column_info}: #{error.problem}"
+    end
+    # def parse_yaml(content)
+    #   YAML.safe_load(content, permitted_classes: [Symbol, Time], aliases: true)
+    # end
+
+    def parse_json(content, path)
+      JSON.parse(content, symbolize_names: true)
+    rescue JSON::ParserError => error
+      line_match = error.message.match(/at line (\d+)/)
+      line_info = line_match ? " at line #{line_match[1]}" : ""
+
+      raise Errors::DataParseError, "Invalid JSON syntax in `#{path}`#{line_info}: #{error.message}"
+    end
+    # def parse_json(content)
+    #   JSON.parse(content, symbolize_names: true)
+    # end
+
+    def parse_csv(content, path)
+      expected_headers = nil
+
+      CSV.new(content, headers: true, header_converters: :symbol).map.with_index do |row, index|
+        expected_headers ||= row.headers
+
+        if row.headers != expected_headers
+          missing = expected_headers - row.headers
+          extra = row.headers - expected_headers
+
+          error_parts = []
+          error_parts << "missing columns: #{missing.join(", ")}" if missing.any?
+          error_parts << "extra columns: #{extra.join(", ")}" if extra.any?
+
+          raise Errors::DataParseError, "Column mismatch in `#{path}` at row #{index + 2} (#{error_parts.join("; ")}). Expected: #{expected_headers.join(", ")}"
+        end
+
+        row.to_h
+      end
+    rescue CSV::MalformedCSVError => error
+      line_match = error.message.match(/line (\d+)/)
+      line_info = line_match ? " at line #{line_match[1]}" : ""
+
+      raise Errors::DataParseError, "Malformed CSV in `#{path}`#{line_info}: #{error.message}"
+    end
+    # def parse_csv(content)
+    #   CSV.new(content, headers: true, header_converters: :symbol).to_a.map(&:to_h)
+    # end
+  end
+end

data/lib/perron/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "perron/output_server"
+require "mata"
 
 module Perron
   class Engine < Rails::Engine
@@ -12,6 +13,17 @@ module Perron
       app.middleware.use Perron::OutputServer
     end
 
+    initializer "perron.configure_hmr", after: :load_config_initializers do |app|
+      if Rails.env.development? && Perron.configuration.live_reload
+        app.config.middleware.insert_before(
+          ActionDispatch::Static,
+          Mata,
+          watch: Perron.configuration.live_reload_watch_paths,
+          skip: Perron.configuration.live_reload_skip_paths
+        )
+      end
+    end
+
     rake_tasks do
       load File.expand_path("../tasks/build.rake", __FILE__)
       load File.expand_path("../tasks/clobber.rake", __FILE__)

data/lib/perron/html_processor/syntax_highlight.rb

@@ -7,6 +7,8 @@ module Perron
   class HtmlProcessor
     class SyntaxHighlight < HtmlProcessor::Base
       def process
+        Perron.deprecator.deprecation_warning(:syntax_highlight)
+
         @html.css('pre > code[class*="language-"]').each do |code_block|
           language = code_block[:class][/(?<=language-)\S+/]
 

data/lib/perron/output_server.rb

@@ -27,21 +27,26 @@ module Perron
 
     def serve(file_path)
       content = File.read(file_path)
+      injected_content = inject_preview_indicator(content)
 
       [
         200,
 
         {
           "Content-Type" => "text/html; charset=utf-8",
-          "Content-Length" => content.bytesize.to_s
+          "Content-Length" => injected_content.bytesize.to_s
         },
 
-        [content]
+        [injected_content]
       ]
     end
 
     def enabled? = Dir.exist?(output_path)
 
+    def inject_preview_indicator(content)
+      content.gsub(/<title>(.*?)<\/title>/i, "<title>[PREVIEW] \\1</title>")
+    end
+
     def output_path
       @output_path ||= Rails.root.join(Perron.configuration.output)
     end

data/lib/perron/relation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Perron
+  class Relation < Array
+    def initialize(resources = [])
+      super
+    end
+
+    def where(**conditions)
+      filtered = select do |resource|
+        conditions.all? do |key, value|
+          key_value = resource.public_send(key)
+
+          if value.is_a?(Array)
+            value.map(&:to_s).include?(key_value.to_s)
+          else
+            key_value.to_s == value.to_s
+          end
+        end
+      end
+
+      Relation.new(filtered)
+    end
+
+    def limit(count) = Relation.new(first(count))
+
+    def offset(count) = Relation.new(drop(count))
+
+    def order(attribute, direction = :asc)
+      if attribute.is_a?(Hash)
+        attribute, direction = attribute.first
+      end
+
+      sorted = sort_by { it.public_send(attribute) }
+
+      Relation.new((direction == :desc) ? sorted.reverse : sorted)
+    end
+
+    def pluck(*attributes)
+      raise ArgumentError, "wrong number of arguments (given 0, expected 1+)" if attributes.empty?
+
+      map do |resource|
+        if attributes.size == 1
+          resource.public_send(attributes.first)
+        else
+          attributes.map { resource.public_send(it) }
+        end
+      end
+    end
+  end
+end

data/lib/perron/resource/associations.rb

@@ -66,7 +66,7 @@ module Perron
       def records_for_ids(associated_class, ids)
         ids = Array(ids)
 
-        associated_class.all.select { ids.include?(it[:id]) || ids.include?(it["id"]) }
+        Perron::Relation.new(associated_class.all.select { ids.include?(it[:id]) || ids.include?(it["id"]) })
       end
 
       def records_for_foreign_key(associated_class, association_name, **options)
@@ -74,7 +74,7 @@ module Perron
         primary_key_method = options.fetch(:primary_key, :slug)
         lookup_value = public_send(primary_key_method)
 
-        associated_class.all.select { it.association_value(foreign_key) == lookup_value }
+        Perron::Relation.new(associated_class.all.select { it.association_value(foreign_key) == lookup_value })
       end
 
       def inverse_association_name = self.class.name.demodulize.underscore

data/lib/perron/resource/class_methods.rb

@@ -8,10 +8,20 @@ module Perron
       class_methods do
         def find(slug) = collection.find(slug, name.constantize)
 
+        def find!(slug) = collection.find!(slug, name.constantize)
+
         def all = collection.all(self)
 
+        def where(**conditions) = all.where(**conditions)
+
+        def limit(count) = all.limit(count)
+
+        def offset(count) = all.offset(count)
+
         def count = all.size
 
+        def order(attribute, direction = :asc) = all.order(attribute, direction)
+
         def first(n = nil)
           n ? all.first(n) : all[0]
         end

data/lib/perron/resource/configuration.rb

@@ -22,8 +22,6 @@ module Perron
             config.feeds.json.path = "feeds/#{collection.name.demodulize.parameterize}.json"
             config.feeds.json.max_items = 20
 
-            config.linked_data = ActiveSupport::OrderedOptions.new
-
             config.related_posts = ActiveSupport::OrderedOptions.new
             config.related_posts.enabled = false
             config.related_posts.max = 5
@@ -39,18 +37,17 @@ module Perron
       end
 
       class Options < ActiveSupport::OrderedOptions
-        def method_missing(name, *arguments)
-          if name.to_s.end_with?("=")
-            key = name.to_s.chomp("=").to_sym
-            value = arguments.first
-
-            return self[key].merge!(value) if self[key].is_a?(ActiveSupport::OrderedOptions) && value.is_a?(Hash)
+        def []=(key, value)
+          if self[key].is_a?(ActiveSupport::OrderedOptions) && value.is_a?(Hash)
+            self[key].merge!(value)
+          else
+            super
           end
-
-          super
         end
 
-        def respond_to_missing?(name, include_private = false) = super
+        def respond_to_missing?(name, include_private = false)
+          name.to_s.end_with?("=") || super
+        end
       end
       private_constant :Options
     end

data/lib/perron/resource/core.rb

@@ -10,6 +10,17 @@ module Perron
       def to_model = self
 
       def model_name = self.class.model_name
+
+      def association_value(key) = metadata[key]
+
+      def to_partial_path
+        @to_partial_path ||= begin
+          element = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.demodulize(self.class.model_name))
+          collection = ActiveSupport::Inflector.tableize(self.class.model_name)
+
+          File.join("content", collection, element)
+        end
+      end
     end
   end
 end

data/lib/perron/resource/related/stop_words.rb

@@ -5,28 +5,28 @@ module Perron
     class Resource
       class Related
         module StopWords
+          ALL = Set[
+            "a", "about", "above", "after", "again", "against", "all", "am",
+            "an", "and", "any", "are", "as", "at", "be", "because", "been",
+            "before", "being", "below", "between", "both", "but", "by", "can",
+            "did", "do", "does", "doing", "down", "during", "each", "few",
+            "for", "from", "further", "had", "has", "have", "having", "he",
+            "her", "here", "hers", "herself", "him", "himself", "his", "how",
+            "i", "if", "in", "into", "is", "it", "its", "itself", "just",
+            "me", "more", "most", "my", "myself", "no", "nor", "not", "now",
+            "of", "off", "on", "once", "only", "or", "other", "our", "ours",
+            "ourselves", "out", "over", "own", "s", "same", "she", "should",
+            "so", "some", "such", "t", "than", "that", "the", "their",
+            "theirs", "them", "themselves", "then", "there", "these", "they",
+            "this", "those", "through", "to", "too", "under", "until", "up",
+            "very", "was", "we", "were", "what", "when", "where", "which",
+            "while", "who", "whom", "why", "will", "with", "you", "your",
+            "yours", "yourself", "yourselves"
+          ].freeze
+
           module_function
 
-          def all
-            Set[
-              "a", "about", "above", "after", "again", "against", "all", "am",
-              "an", "and", "any", "are", "as", "at", "be", "because", "been",
-              "before", "being", "below", "between", "both", "but", "by", "can",
-              "did", "do", "does", "doing", "down", "during", "each", "few",
-              "for", "from", "further", "had", "has", "have", "having", "he",
-              "her", "here", "hers", "herself", "him", "himself", "his", "how",
-              "i", "if", "in", "into", "is", "it", "its", "itself", "just",
-              "me", "more", "most", "my", "myself", "no", "nor", "not", "now",
-              "of", "off", "on", "once", "only", "or", "other", "our", "ours",
-              "ourselves", "out", "over", "own", "s", "same", "she", "should",
-              "so", "some", "such", "t", "than", "that", "the", "their",
-              "theirs", "them", "themselves", "then", "there", "these", "they",
-              "this", "those", "through", "to", "too", "under", "until", "up",
-              "very", "was", "we", "were", "what", "when", "where", "which",
-              "while", "who", "whom", "why", "will", "with", "you", "your",
-              "yours", "yourself", "yourselves"
-            ]
-          end
+          def all = ALL
         end
       end
     end

data/lib/perron/resource/related.rb

@@ -5,93 +5,114 @@ require "perron/resource/related/stop_words"
 module Perron
   module Site
     class Resource
+      # Finds related resources using TF-IDF cosine similarity.
+      #
+      # Pre-normalizes vectors so cosine similarity reduces to a dot product,
+      # then builds a symmetric similarity matrix once per collection.
+      # Results are cached at the class level so the O(n²) comparison
+      # is paid once, not once per resource.
       class Related
+        Cache = Struct.new(:resources, :similarity_matrix, :fingerprint)
+
+        @collection_caches = {}
+
+        def self.cache_for(collection_name)
+          clear_cache!(collection_name) if stale?(collection_name)
+          @collection_caches[collection_name] ||= Cache.new(nil, nil, content_fingerprint(collection_name))
+        end
+
+        def self.clear_cache!(collection_name)
+          @collection_caches.delete(collection_name)
+        end
+
+        def self.stale?(collection_name)
+          @collection_caches[collection_name]&.fingerprint != content_fingerprint(collection_name)
+        end
+
+        def self.content_fingerprint(collection_name)
+          path = File.join(Perron.configuration.input, collection_name)
+          files = Dir.glob(File.join(path, "**", "*.*"))
+          [files.size, files.map { File.mtime(it) }.max]
+        end
+
         def initialize(resource)
           @resource = resource
           @collection = resource.collection
+          @cache = self.class.cache_for(@collection.name)
         end
 
         def find(limit: 5)
-          @collection.resources
+          scores = similarity_matrix[@resource.slug] || {}
+
+          resources
             .reject { it.slug == @resource.slug }
-            .map { [it, cosine_similarities_for(@resource, it)] }
-            .sort_by { |_, score| -score }
-            .map(&:first)
+            .sort_by { -(scores[it.slug] || 0.0) }
             .first(limit)
         end
 
         private
 
-        def cosine_similarities_for(resource_one, resource_two)
-          first_vector = tfidf_vector_for(resource_one)
-          second_vector = tfidf_vector_for(resource_two)
+        def resources = @cache.resources ||= @collection.resources
 
-          return 0.0 if first_vector.empty? || second_vector.empty?
+        def similarity_matrix = @cache.similarity_matrix ||= build_similarity_matrix
 
-          dot_product = 0.0
+        def build_similarity_matrix
+          vectors = resources.to_h { [it.slug, normalize(tfidf_vector_for(it))] }
+          matrix = Hash.new { |h, k| h[k] = {} }
 
-          first_vector.each_key { dot_product += first_vector[it] * second_vector[it] if second_vector.key?(it) }
+          slugs = vectors.keys
+          slugs.each_with_index do |slug_a, i|
+            next if vectors[slug_a].empty?
 
-          first_magnitude = Math.sqrt(first_vector.values.sum { it**2 })
-          second_magnitude = Math.sqrt(second_vector.values.sum { it**2 })
-          denominator = first_magnitude * second_magnitude
+            slugs[(i + 1)..].each do |slug_b|
+              next if vectors[slug_b].empty?
 
-          return 0.0 if denominator.zero?
+              score = dot_product(vectors[slug_a], vectors[slug_b])
+              matrix[slug_a][slug_b] = score
+              matrix[slug_b][slug_a] = score
+            end
+          end
 
-          dot_product / denominator
+          matrix
         end
 
-        def tfidf_vector_for(target_resource)
-          @tfidf_vectors ||= {}
-
-          return @tfidf_vectors[target_resource] if @tfidf_vectors.key?(target_resource)
-
-          tokens = tokenize_content(target_resource)
-          token_count = tokens.size
-
-          return {} if token_count.zero?
+        def dot_product(vec_a, vec_b)
+          score = 0.0
+          vec_a.each_key { score += vec_a[it] * vec_b[it] if vec_b.key?(it) }
+          score
+        end
 
-          term_count = Hash.new(0)
+        def normalize(vector)
+          return {} if vector.empty?
 
-          tokens.each { |token| term_count[token] += 1 }
+          magnitude = Math.sqrt(vector.values.sum { it**2 })
+          return {} if magnitude.zero?
 
-          tfidf_vector = {}
+          vector.transform_values { it / magnitude }
+        end
 
-          term_count.each do |term, count|
-            terms = count.to_f / token_count
+        def tfidf_vector_for(resource)
+          tokens = tokenize(resource)
+          return {} if tokens.empty?
 
-            tfidf_vector[term] = terms * inverse_document_frequency[term]
-          end
+          token_count = tokens.size.to_f
 
-          @tfidf_vectors[target_resource] = tfidf_vector
+          tokens.tally.to_h { |term, count| [term, (count / token_count) * inverse_document_frequency[term]] }
         end
 
-        def tokenize_content(target_resource)
-          @tokenized_content ||= {}
+        def tokenize(resource)
+          return [] if resource.content.blank?
 
-          return @tokenized_content[target_resource] if @tokenized_content.key?(target_resource)
-          return [] if target_resource.content.blank?
-
-          content = target_resource.content.gsub(/<[^>]*>/, " ")
-          tokens = content.downcase.scan(/\w+/).reject { StopWords.all.include?(it) || it.length < 3 }
-
-          @tokenized_content[target_resource] = tokens
+          resource.content.gsub(/<[^>]*>/, " ").downcase.scan(/\w+/).reject { StopWords.all.include?(it) || it.length < 3 }
         end
 
         def inverse_document_frequency
           @inverse_document_frequency ||= begin
-            resource_frequency = Hash.new(0)
-
-            @collection.resources.each { tokenize_content(it).uniq.each { resource_frequency[it] += 1 } }
-
-            frequencies = {}
-            total_resources = @collection.resources.size
-
-            resource_frequency.each do |term, frequency|
-              frequencies[term] = Math.log(total_resources.to_f / (1 + frequency))
-            end
+            doc_frequency = Hash.new(0)
+            resources.each { tokenize(it).uniq.each { doc_frequency[it] += 1 } }
 
-            frequencies
+            total = resources.size.to_f
+            doc_frequency.transform_values { Math.log(total / (1 + it)) }
           end
         end
       end

data/lib/perron/resource/scopes.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Perron
+  class Resource
+    module Scopes
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def scope(name, body)
+          unless body.respond_to?(:call)
+            raise ArgumentError, "The scope body needs to be callable."
+          end
+
+          if respond_to?(name, true)
+            raise ArgumentError, "Cannot define scope :#{name} because it already exists."
+          end
+
+          singleton_class.define_method(name) do |*arguments|
+            instance_exec(*arguments, &body)
+          end
+
+          Perron::Relation.define_method(name) do |*arguments|
+            instance_exec(*arguments, &body)
+          end
+        end
+      end
+    end
+  end
+end