perron 0.17.0 → 1.0.0

data/lib/perron/resource/related.rb

@@ -5,93 +5,115 @@ 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, fingerprinted(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 != fingerprinted(collection_name)
+        end
+
+        def self.fingerprinted(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)
-
-          return 0.0 if first_vector.empty? || second_vector.empty?
-
-          dot_product = 0.0
-
-          first_vector.each_key { dot_product += first_vector[it] * second_vector[it] if second_vector.key?(it) }
-
-          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
-
-          return 0.0 if denominator.zero?
+        def resources
+          @cache.resources ||= @collection.resources
+        end
 
-          dot_product / denominator
+        def similarity_matrix
+          @cache.similarity_matrix ||= build_similarity_matrix
         end
 
-        def tfidf_vector_for(target_resource)
-          @tfidf_vectors ||= {}
+        def build_similarity_matrix
+          vectors = resources.to_h { [it.slug, normalize(tfidf_vector_for(it))] }
 
-          return @tfidf_vectors[target_resource] if @tfidf_vectors.key?(target_resource)
+          Hash.new { |hash, key| hash[key] = {} }.tap do |matrix|
+            slugs = vectors.keys
 
-          tokens = tokenize_content(target_resource)
-          token_count = tokens.size
+            slugs.each_with_index do |slug_a, index|
+              next if vectors[slug_a].empty?
 
-          return {} if token_count.zero?
+              slugs[(index + 1)..].each do |slug_b|
+                next if vectors[slug_b].empty?
 
-          term_count = Hash.new(0)
+                matrix[slug_a][slug_b] = dot_product(vectors[slug_a], vectors[slug_b])
+                matrix[slug_b][slug_a] = matrix[slug_a][slug_b]
+              end
+            end
+          end
+        end
 
-          tokens.each { |token| term_count[token] += 1 }
+        def normalize(vector)
+          magnitude = Math.sqrt(vector.values.sum { it**2 })
+          return {} if vector.empty? || 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 = tokenized(resource)
+          return {} if tokens.empty?
 
-            tfidf_vector[term] = terms * inverse_document_frequency[term]
-          end
-
-          @tfidf_vectors[target_resource] = tfidf_vector
+          token_count = tokens.size.to_f
+          tokens.tally.to_h { |term, count| [term, (count / token_count) * inverse_document_frequency[term]] }
         end
 
-        def tokenize_content(target_resource)
-          @tokenized_content ||= {}
-
-          return @tokenized_content[target_resource] if @tokenized_content.key?(target_resource)
-          return [] if target_resource.content.blank?
+        def dot_product(vector_a, vector_b)
+          vector_a.sum { |term, value| value * (vector_b[term] || 0) }
+        end
 
-          content = target_resource.content.gsub(/<[^>]*>/, " ")
-          tokens = content.downcase.scan(/\w+/).reject { StopWords.all.include?(it) || it.length < 3 }
+        def tokenized(resource)
+          return [] if resource.content.blank?
 
-          @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
+            document_frequency = Hash.new(0)
+            resources.each { tokenized(it).uniq.each { document_frequency[it] += 1 } }
 
-            frequencies
+            total = resources.size.to_f
+            document_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

data/lib/perron/resource/searchable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Perron
+  class Resource
+    module Searchable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :search_fields_list, default: []
+      end
+
+      class_methods do
+        def search_fields(*fields)
+          self.search_fields_list = fields
+        end
+      end
+    end
+  end
+end

data/lib/perron/resource/sourceable.rb

@@ -15,6 +15,18 @@ module Perron
           @source_definitions || {}
         end
 
+        def resolve(name)
+          definition = source_definitions[name]
+
+          data = if definition[:class]
+            definition[:class].all
+          else
+            Perron::DataSource.new(name.to_s).to_a
+          end
+
+          definition[:scope] ? definition[:scope].call(data) : data
+        end
+
         def source_names = source_definitions.keys
 
         def generate_from_sources!
@@ -36,20 +48,36 @@ module Perron
         def parsed(*arguments)
           return {} if arguments.empty?
 
-          arguments.flat_map { it.is_a?(Hash) ? it.to_a : [[it, {primary_key: :id}]] }.to_h
+          arguments.flat_map do |argument|
+            case argument
+            when Hash
+              argument.to_a
+            when Proc
+              [[SecureRandom.hex(8).to_sym, {scope: argument, primary_key: :id}]]
+            else
+              [[argument, {primary_key: :id}]]
+            end
+          end.to_h
         end
 
         def combinations
-          datasets = source_names.map { Perron::Data.new(it.to_s) }
+          datasets = source_names.map { resolve it }
+
+          datasets.first.product(*datasets[1..]).each do |combo|
+            combo.each_with_index do |item, index|
+              name = source_names[index]
+              primary_key = source_definitions[name][:primary_key] || :id
 
-          datasets.first.product(*datasets[1..])
+              raise Errors::DataParseError, "Primary key `#{primary_key}` is nil for row in source `#{name}`" if item.public_send(primary_key).nil?
+            end
+          end
         end
 
         def content_with(combo)
           data = source_names.each.with_index.to_h { |name, index| [name, combo[index]] }
-          sources = Source.new(data)
+          source = Source.new(data)
 
-          source_template(sources)
+          source_template(source)
         end
 
         def filename_with(combo)
@@ -65,21 +93,23 @@ module Perron
 
       def source_backed? = self.class.source_backed?
 
-      def sources
-        @sources ||= begin
+      def source
+        @source ||= begin
           data = self.class.source_definitions.each_with_object({}) do |(name, options), hash|
             primary_key = options[:primary_key]
             singular_name = name.to_s.singularize
             identifier = frontmatter["#{singular_name}_#{primary_key}"]
 
-            hash[name] = Perron::Data.new(name.to_s).find { it.public_send(primary_key).to_s == identifier.to_s }
+            dataset = self.class.send(:resolve, name)
+            hash[name] = dataset.find { it.public_send(primary_key).to_s == identifier.to_s }
           end
 
           Source.new(data)
         end
       end
+      alias_method :sources, :source
 
-      def source_template(sources)
+      def source_template(source)
         raise NotImplementedError, "#{self.class.name} must implement #source_template"
       end
 

data/lib/perron/resource/sweeper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Perron
+  class Resource
+    module Sweeper
+      extend ActiveSupport::Concern
+
+      def extracted_headings
+        extract_heading_texts(from: rendered_document)
+      end
+
+      def sweeped_content
+        ActionView::Base.full_sanitizer.sanitize(
+          rendered_document.text.gsub(/\s+/, " ").strip
+        )
+      end
+
+      private
+
+      def rendered_document
+        @rendered_document ||= Nokogiri::HTML::DocumentFragment.parse(Markdown.render(content))
+      end
+
+      def extract_heading_texts(from:, levels: "h1, h2, h3, h4, h5, h6")
+        from.css(levels).map { it.text.strip }.compact_blank
+      end
+
+      def extract_headings(from:, levels:)
+        from.css(levels).each_with_object([]) do |heading, headings|
+          heading_text = heading.text.strip
+          id = heading["id"] || heading.at("a")&.[]("id")
+
+          next if heading_text.empty? || id.blank?
+
+          headings << TableOfContent::Item.new(
+            id: id,
+            text: heading_text,
+            level: heading.name[1..].to_i,
+            children: []
+          )
+        end
+      end
+    end
+  end
+end

data/lib/perron/resource/table_of_content.rb

@@ -20,24 +20,6 @@ module Perron
 
       Item = ::Data.define(:id, :text, :level, :children)
 
-      def extract_headings(from:, levels:)
-        from.css(levels).each_with_object([]) do |heading, headings|
-          heading.tap do |node|
-            heading_text = node.text.strip
-            id = node["id"] || node.at("a")&.[]("id")
-
-            next if heading_text.empty? || id.blank?
-
-            headings << Item.new(
-              id: id,
-              text: heading_text,
-              level: node.name[1..].to_i,
-              children: []
-            )
-          end
-        end
-      end
-
       class Builder
         def build(headings)
           parents = {0 => {children: []}}

data/lib/perron/resource.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "perron/relation"
 require "perron/resource/configuration"
 require "perron/resource/core"
 require "perron/resource/class_methods"
@@ -10,26 +11,32 @@ require "perron/resource/publishable"
 require "perron/resource/reading_time"
 require "perron/resource/related"
 require "perron/resource/renderer"
+require "perron/resource/scopes"
 require "perron/resource/slug"
+require "perron/resource/searchable"
 require "perron/resource/separator"
 require "perron/resource/sourceable"
+require "perron/resource/sweeper"
+require "perron/resource/adjacency"
 require "perron/resource/table_of_content"
 
 module Perron
   class Resource
-    ID_LENGTH = 8
-
     include ActiveModel::Validations
 
-    include Perron::Resource::Configuration
-    include Perron::Resource::Core
-    include Perron::Resource::ClassMethods
-    include Perron::Resource::Associations
-    include Perron::Resource::ReadingTime
-    include Perron::Resource::Sourceable
-    include Perron::Resource::Publishable
-    include Perron::Resource::Previewable
-    include Perron::Resource::TableOfContent
+    include Configuration
+    include Core
+    include ClassMethods
+    include Associations
+    include ReadingTime
+    include Searchable
+    include Sourceable
+    include Publishable
+    include Previewable
+    include Scopes
+    include Sweeper
+    include Adjacency
+    include TableOfContent
 
     attr_reader :file_path, :id
 
@@ -41,6 +48,16 @@ module Perron
       raise Errors::FileNotFoundError, "No such file: #{file_path}" unless File.exist?(file_path)
     end
 
+    def pluck(*attributes)
+      raise ArgumentError, "wrong number of arguments (given 0, expected 1+)" if attributes.empty?
+
+      if attributes.size == 1
+        public_send(attributes.first)
+      else
+        attributes.map { |attr| public_send(attr) }
+      end
+    end
+
     def filename = File.basename(@file_path)
 
     def slug = Perron::Resource::Slug.new(self, frontmatter).create
@@ -66,15 +83,8 @@ module Perron
       render_inline_erb using: page_content
     end
 
-    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
+    def inline(layout: "application", **options)
+      {html: content, layout: layout}.merge(options)
     end
 
     def collection = Collection.new(self.class.model_name.collection)
@@ -88,6 +98,8 @@ module Perron
 
     private
 
+    ID_LENGTH = 8
+
     def frontmatter
       @frontmatter ||= Perron::Resource::Separator.new(raw_content).frontmatter
     end

data/lib/perron/site/builder/assets.rb

@@ -11,7 +11,7 @@ module Perron
         def prepare
           puts "📦 Precompiling and copying assets…"
 
-          success = system("bundle exec rails assets:precompile", out: File::NULL, err: File::NULL)
+          success = system("bundle exec rails assets:precompile", out: File::NULL)
 
           unless success
             puts "❌ ERROR: Asset precompilation failed"

data/lib/perron/site/builder/feeds/atom.erb

@@ -0,0 +1,44 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <generator uri="https://perron.railsdesigner.com/" version="<%= Perron::VERSION %>">Perron</generator>
+  <id><%= current_feed_url.call %></id>
+  <title><%= config.title.presence || @configuration.site_name %></title>
+  <subtitle><%= config.description.presence || @configuration.site_description %></subtitle>
+  <link href="<%= current_feed_url.call %>" rel="self" type="application/atom+xml"/>
+  <link href="<%= @configuration.url %>" rel="alternate" type="text/html"/>
+  <updated><%= resources.first&.published_at&.iso8601 || Time.current.iso8601 %></updated>
+
+  <% feed_author = config.author || { name: @configuration.site_name, email: "noreply@#{URI.parse(@configuration.url).host}" } %>
+  <author>
+    <% if feed_author[:name] %><name><%= feed_author[:name] %></name><% end %>
+    <% if feed_author[:email] %><email><%= feed_author[:email] %></email><% end %>
+  </author>
+
+  <% resources.each do |resource| %>
+  <entry>
+    <id><%= url_for_resource.call(resource) || "#{@configuration.url}/posts/#{resource.id}" %></id>
+    <title><%= resource.metadata.title %></title>
+    <link href="<%= url_for_resource.call(resource) %>" rel="alternate" type="text/html"/>
+    <published><%= resource.published_at&.iso8601 %></published>
+    <updated><%= (resource.metadata.updated_at || resource.published_at)&.iso8601 %></updated>
+
+    <% entry_author = author.call(resource); if entry_author %>
+      <author>
+        <% if entry_author.name %><name><%= entry_author.name %></name><% end %>
+        <% if entry_author.email %><email><%= entry_author.email %></email><% end %>
+      </author>
+    <% end %>
+
+    <% base_url = url_for_resource.call(resource) %>
+    <% if base_url %>
+      <content type="html" xml:base="<%= base_url %>"><![CDATA[<%= Perron::Markdown.render(resource.content, processors: ["absolute_urls"]) %>]]></content>
+    <% else %>
+      <content type="html"><![CDATA[<%= Perron::Markdown.render(resource.content, processors: ["absolute_urls"]) %>]]></content>
+    <% end %>
+
+    <% resource.metadata.tags&.each do |tag| %>
+      <category term="<%= tag %>"/>
+    <% end %>
+  </entry>
+  <% end %>
+</feed>

data/lib/perron/site/builder/feeds/atom.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "perron/site/builder/feeds/author"
+require "perron/site/builder/feeds/template"
+
+module Perron
+  module Site
+    class Builder
+      class Feeds
+        class Atom
+          include Feeds::Author
+          include Feeds::Template
+
+          def initialize(collection:)
+            @collection = collection
+            @configuration = Perron.configuration
+          end
+
+          def generate
+            return if resources.empty?
+
+            template = find_template("atom")
+            return unless template
+
+            render(template, feed_configuration)
+          end
+
+          private
+
+          def resources
+            @resource ||= @collection.resources
+              .reject { it.metadata.feed == false }
+              .sort_by { it.metadata.published_at || it.metadata.updated_at || Time.current }
+              .reverse
+              .take(feed_configuration.max_items)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/perron/site/builder/feeds/json.erb

@@ -0,0 +1,19 @@
+<%= {
+  generator: "Perron (#{Perron::VERSION})",
+  version: "https://jsonfeed.org/version/1.1",
+  home_page_url: @configuration.url,
+  title: config.title.presence || @configuration.site_name,
+  description: config.description.presence || @configuration.site_description,
+
+  items: resources.map { |resource|
+    item_author = author.call(resource)
+    {
+      id: resource.id,
+      url: url_for_resource.call(resource),
+      date_published: resource.published_at&.iso8601,
+      title: resource.metadata.title,
+      authors: (item_author && item_author.name ? [{ name: item_author.name, email: item_author.email, url: item_author.url, avatar: item_author.avatar }.compact] : nil),
+      content_html: Perron::Markdown.render(resource.content, processors: ["absolute_urls"])
+    }.compact
+  }
+}.to_json %>

data/lib/perron/site/builder/feeds/json.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "json"
 require "perron/site/builder/feeds/author"
+require "perron/site/builder/feeds/template"
 
 module Perron
   module Site
@@ -9,6 +9,7 @@ module Perron
       class Feeds
         class Json
           include Feeds::Author
+          include Feeds::Template
 
           def initialize(collection:)
             @collection = collection
@@ -16,50 +17,23 @@ module Perron
           end
 
           def generate
-            return nil if resources.empty?
+            return if resources.empty?
 
-            hash = Rails.application.routes.url_helpers.with_options(@configuration.default_url_options) do |url|
-              {
-                generator: "Perron (#{Perron::VERSION})",
-                version: "https://jsonfeed.org/version/1.1",
-                home_page_url: @configuration.url,
-                title: feed_configuration.title.presence || @configuration.site_name,
-                description: feed_configuration.description.presence || @configuration.site_description,
-                items: resources.map do |resource|
-                  {
-                    id: resource.id,
-                    url: url.polymorphic_url(resource, ref: feed_configuration.ref).delete_suffix("?ref="),
-                    date_published: resource.published_at&.iso8601,
-                    authors: authors(resource),
-                    title: resource.metadata.title,
-                    content_html: Perron::Markdown.render(resource.content)
-                  }
-                end
-              }
-            end
+            template = find_template("json")
+            return unless template
 
-            JSON.pretty_generate hash
+            render(template, feed_configuration)
           end
 
           private
 
           def resources
-            @resources ||= @collection.resources
+            @resource ||= @collection.resources
               .reject { it.metadata.feed == false }
               .sort_by { it.metadata.published_at || it.metadata.updated_at || Time.current }
               .reverse
               .take(feed_configuration.max_items)
           end
-
-          def feed_configuration = @collection.configuration.feeds.json
-
-          def authors(resource)
-            author = author(resource)
-
-            return nil unless author&.name
-
-            [{name: author.name, email: author.email, url: author.url, avatar: author.avatar}.compact].presence
-          end
         end
       end
     end