perron 0.18.0 → 1.0.0

data/lib/perron/engine.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "perron/output_server"
+require "perron/development_feed_server"
 require "mata"
 
 module Perron
@@ -10,7 +11,11 @@ module Perron
     end
 
     initializer "perron.output_server" do |app|
-      app.middleware.use Perron::OutputServer
+      app.middleware.use Perron::OutputServer if Rails.env.development?
+    end
+
+    initializer "perron.development_feed_server" do |app|
+      app.middleware.use Perron::DevelopmentFeedServer if Rails.env.development?
     end
 
     initializer "perron.configure_hmr", after: :load_config_initializers do |app|
@@ -24,9 +29,32 @@ module Perron
       end
     end
 
+    initializer "perron.concierge", before: :add_builtin_route do |app|
+      app.config.after_initialize do
+        app.routes.append do
+          namespace :perron do
+            post :run_command, to: "concierge#run_command"
+          end
+
+          root to: "perron/concierge#show" unless app.routes.named_routes.key?(:root)
+        end
+      end
+
+      app.routes.finalize!
+    end
+
+    initializer "perron.inflections" do
+      ActiveSupport::Inflector.inflections(:en) do |inflect|
+        inflect.acronym "RSS"
+        inflect.acronym "Atom"
+        inflect.acronym "Json"
+      end
+    end
+
     rake_tasks do
       load File.expand_path("../tasks/build.rake", __FILE__)
       load File.expand_path("../tasks/clobber.rake", __FILE__)
+      load File.expand_path("../tasks/install.rake", __FILE__)
       load File.expand_path("../tasks/sync_sources.rake", __FILE__)
       load File.expand_path("../tasks/validate.rake", __FILE__)
     end

data/lib/perron/errors.rb

@@ -10,6 +10,8 @@ module Perron
 
     class DataParseError < StandardError; end
 
+    class DataSourceNotFoundError < StandardError; end
+
     class ProcessorNotFoundError < StandardError; end
 
     class InvalidProcessorError < StandardError; end

data/lib/perron/feeds.rb

@@ -19,7 +19,7 @@ module Perron
             next unless feed.enabled && feed.path && MIME_TYPES.key?(type)
 
             absolute_url = URI.join(url.root_url, feed.path).to_s
-            title = "#{collection.name.humanize} #{type.to_s.upcase} Feed"
+            title = "#{collection.name.humanize} #{type.to_s.humanize} Feed"
 
             html_tags << tag(:link, rel: "alternate", type: MIME_TYPES[type], title: title, href: absolute_url)
           end
@@ -32,8 +32,9 @@ module Perron
     private
 
     MIME_TYPES = {
-      rss: "application/rss+xml",
-      json: "application/json"
+      atom: "application/atom+xml",
+      json: "application/json",
+      rss: "application/rss+xml"
     }
   end
 end

data/lib/perron/html_processor/absolute_urls.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Perron
+  class HtmlProcessor
+    class AbsoluteUrls < HtmlProcessor::Base
+      def process
+        @html.css("img").each do |image|
+          src = image["src"]
+
+          next if src.blank? || absolute_url?(src)
+
+          image["src"] = base_url + src
+        end
+      end
+
+      private
+
+      def absolute_url?(src)
+        src.start_with?("http://", "https://", "//")
+      end
+
+      def base_url
+        Perron.configuration.url.delete_suffix("/")
+      end
+    end
+  end
+end

data/lib/perron/html_processor/base.rb

@@ -3,8 +3,8 @@
 module Perron
   class HtmlProcessor
     class Base
-      def initialize(html)
-        @html = html
+      def initialize(html, resource: nil)
+        @html, @resource = html, resource
       end
 
       def process

data/lib/perron/html_processor.rb

@@ -2,17 +2,19 @@
 
 require "perron/html_processor/target_blank"
 require "perron/html_processor/lazy_load_images"
+require "perron/html_processor/absolute_urls"
 
 module Perron
   class HtmlProcessor
-    def initialize(html, processors: [])
+    def initialize(html, processors: [], resource: nil)
       @html = html
+      @resource = resource
       @processors = processors.map { find_by(it) }
     end
 
     def process
       Nokogiri::HTML::DocumentFragment.parse(@html).tap do |document|
-        @processors.each { it.new(document).process }
+        @processors.each { it.new(document, resource: @resource).process }
       end.to_html
     end
 
@@ -20,14 +22,9 @@ module Perron
 
     BUILT_IN = {
       "target_blank" => Perron::HtmlProcessor::TargetBlank,
-      "lazy_load_images" => Perron::HtmlProcessor::LazyLoadImages
-    }.tap do |processors|
-      require "rouge"
-      require "perron/html_processor/syntax_highlight"
-
-      processors["syntax_highlight"] = Perron::HtmlProcessor::SyntaxHighlight
-    rescue LoadError
-    end
+      "lazy_load_images" => Perron::HtmlProcessor::LazyLoadImages,
+      "absolute_urls" => Perron::HtmlProcessor::AbsoluteUrls
+    }
 
     def find_by(identifier)
       case identifier
@@ -47,7 +44,6 @@ module Perron
 
       return processor if processor
 
-      raise Perron::Errors::ProcessorNotFoundError, "The `syntax_highlight` processor requires `rouge`. Run `bundle add rouge` to add it to your Gemfile." if name.inquiry.syntax_highlight?
       raise Perron::Errors::ProcessorNotFoundError, "Could not find processor `#{name}`. It is not a Perron-included processor and the constant `#{name.camelize}` could not be found."
     end
   end

data/lib/{generators/perron/templates → perron/install}/README.md.tt

@@ -7,10 +7,10 @@ Perron can consume structured data from YML, JSON or CSV files, making them avai
 
 Access data sources using the `Content::Data` namespace with the class name matching the file's basename:
 ```erb
-<%% Content::Data::Features.all.each do |feature| %>
-  <h4><%%= feature.name %></h4>
-  <p><%%= feature.description %></p>
-<%% end %>
+<% Content::Data::Features.all.each do |feature| %>
+  <h4><%= feature.name %></h4>
+  <p><%= feature.description %></p>
+<% end %>
 ```
 
 Look up a single entry with `Content::Data::Features.find("advanced-search")`, where `"advanced-search"` matches the value of the entry's `id` field.
@@ -34,15 +34,15 @@ feature[:name]
 
 Render data collections directly using Rails-like partial rendering:
 ```erb
-<%%= render Content::Data::Features.all %>
+<%= render Content::Data::Features.all %>
 ```
 
 This expects a partial at `app/views/content/features/_feature.html.erb` that will be rendered once for each item in `Content::Data::Features.all`. The individual record is made available as a local variable matching the singular form of the collection name.
 ```erb
 <!-- app/views/content/features/_feature.html.erb -->
 <div class="feature">
-  <h4><%%= feature.name %></h4>
-  <p><%%= feature.description %></p>
+  <h4><%= feature.name %></h4>
+  <p><%= feature.description %></p>
 </div>
 ```
 
@@ -64,6 +64,4 @@ Data resources must contain an array of objects. Each record should include an `
 
 ## Enumerable methods
 
-[!label v0.17.0+]
-
 All data objects support enumerable methods like `select`, `sort_by`, `first` and `count`. See [Enumerable methods](/docs/rendering/#enumerable-methods) for the full list of available methods.

data/lib/perron/install.rb

@@ -0,0 +1,23 @@
+say "Install Perron in your Rails app"
+
+say "Create Perron initializer"
+copy_file "#{__dir__}/install/initializer.rb", "config/initializers/perron.rb"
+
+say "Create content data directory"
+copy_file "#{__dir__}/install/README.md", "app/content/data/README.md"
+
+say "Add Markdown gem options to Gemfile"
+append_to_file "Gemfile", <<~RUBY
+
+  # Perron supports Markdown rendering using one of the following gems.
+  # Uncomment your preferred choice and run `bundle install`
+  # gem "commonmarker"
+  # gem "kramdown"
+  # gem "redcarpet"
+RUBY
+
+copy_file "#{__dir__}/assets/icon.png", "public/icon.png", force: true
+copy_file "#{__dir__}/assets/icon.svg", "public/icon.svg", force: true
+
+say "Add output folder to .gitignore"
+append_to_file ".gitignore", "/#{Perron.configuration.output}/\n"

data/lib/perron/markdown.rb

@@ -5,9 +5,9 @@ require "perron/html_processor"
 module Perron
   class Markdown
     class << self
-      def render(text, processors: [])
+      def render(text, processors: [], resource: nil)
         parser.parse(text)
-          .then { Perron::HtmlProcessor.new(it, processors: processors).process }
+          .then { Perron::HtmlProcessor.new(it, processors: processors, resource: resource).process }
           .html_safe
       end
 

data/lib/perron/output_server.rb

@@ -8,6 +8,7 @@ module Perron
 
     def call(environment)
       return @app.call(environment) if disabled?
+      return not_found if !static_file(environment) && Perron.configuration.output_server_strict
 
       static_file(environment).then do |file|
         file ? serve(file) : @app.call(environment)
@@ -41,6 +42,14 @@ module Perron
       ]
     end
 
+    def not_found
+      [
+        404,
+        {"Content-Type" => "text/plain"},
+        ["Not Found"]
+      ]
+    end
+
     def enabled? = Dir.exist?(output_path)
 
     def inject_preview_indicator(content)

data/lib/perron/resource/adjacency.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Perron
+  class Resource
+    module Adjacency
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def adjacent_by(position_method, within: {})
+          return unless within.present?
+
+          grouping_method = within.is_a?(Hash) ? within.keys.first : within
+          grouping_order = within.is_a?(Hash) ? within.values.first : nil
+
+          define_method(:next) do
+            resources = self.class.all.sort_by do |resource|
+              group_value = resource.public_send(grouping_method)
+
+              group_order = if grouping_order
+                grouping_order.index(group_value.to_s) || grouping_order.index(group_value.to_sym) || Float::INFINITY
+              else
+                group_value.to_s
+              end
+
+              [group_order, resource.public_send(position_method)]
+            end
+
+            return if (position = resources.index { it.id == id }).nil? || position >= resources.size - 1
+
+            resources[position + 1]
+          end
+
+          define_method(:previous) do
+            resources = self.class.all.sort_by do |resource|
+              group_value = resource.public_send(grouping_method)
+
+              group_order = if grouping_order
+                grouping_order.index(group_value.to_s) || grouping_order.index(group_value.to_sym) || Float::INFINITY
+              else
+                group_value.to_s
+              end
+
+              [group_order, resource.public_send(position_method)]
+            end
+
+            return if (position = resources.index { it.id == id }).nil? || position <= 0
+
+            resources[position - 1]
+          end
+        end
+      end
+
+      included do
+        define_method(:next) do
+          resources = self.class.all
+          return if (position = resources.index { it.id == id }).nil? || position >= resources.size - 1
+
+          resources[position + 1]
+        end
+
+        define_method(:previous) do
+          resources = self.class.all
+          return if (position = resources.index { it.id == id }).nil? || position <= 0
+
+          resources[position - 1]
+        end
+      end
+    end
+  end
+end

data/lib/perron/resource/associations.rb

@@ -13,7 +13,7 @@ module Perron
               foreign_key = foreign_key_for(association_name, **options)
               identifier = metadata[foreign_key]
 
-              identifier ? associated_class.find(identifier) : nil
+              identifier ? associated_class.find!(identifier) : nil
             end
           end
         end

data/lib/perron/resource/configuration.rb

@@ -12,16 +12,21 @@ module Perron
 
             config.feeds = Options.new
 
-            config.feeds.rss = ActiveSupport::OrderedOptions.new
-            config.feeds.rss.enabled = false
-            config.feeds.rss.path = "feeds/#{collection.name.demodulize.parameterize}.xml"
-            config.feeds.rss.max_items = 20
+            config.feeds.atom = ActiveSupport::OrderedOptions.new
+            config.feeds.atom.enabled = false
+            config.feeds.atom.path = "feeds/#{collection.name.demodulize.parameterize}.atom"
+            config.feeds.atom.max_items = 20
 
             config.feeds.json = ActiveSupport::OrderedOptions.new
             config.feeds.json.enabled = false
             config.feeds.json.path = "feeds/#{collection.name.demodulize.parameterize}.json"
             config.feeds.json.max_items = 20
 
+            config.feeds.rss = ActiveSupport::OrderedOptions.new
+            config.feeds.rss.enabled = false
+            config.feeds.rss.path = "feeds/#{collection.name.demodulize.parameterize}.xml"
+            config.feeds.rss.max_items = 20
+
             config.related_posts = ActiveSupport::OrderedOptions.new
             config.related_posts.enabled = false
             config.related_posts.max = 5

data/lib/perron/resource/metadata.rb

@@ -25,6 +25,8 @@ module Perron
 
         to[:canonical_url] ||= canonical_url
 
+        to[:image] = absolute_url(to[:image]) if to[:image]
+
         to[:og_image] ||= to[:image]
         to[:twitter_image] ||= to[:og_image]
 
@@ -52,13 +54,20 @@ module Perron
         begin
           Rails.application.routes.url_helpers.polymorphic_url(
             @resource,
-          **Perron.configuration.default_url_options
+            **Perron.configuration.default_url_options
           )
         rescue
           false
         end
       end
 
+      def absolute_url(path)
+        return path if path.blank?
+        return path if path.start_with?("http://", "https://", "//")
+
+        Perron.configuration.url.delete_suffix("/") + path
+      end
+
       def site_data
         @config.metadata.except(:title_separator, :title_suffix).deep_symbolize_keys || {}
       end

data/lib/perron/resource/publishable.rb

@@ -7,6 +7,8 @@ module Perron
 
       included do
         def published?
+          return ENV["VIEW_UNPUBLISHED"] == "true" if ENV["VIEW_UNPUBLISHED"]
+
           return true if Perron.configuration.view_unpublished
 
           return false if frontmatter.draft == true

data/lib/perron/resource/related.rb

@@ -9,6 +9,7 @@ module Perron
       #
       # 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
@@ -18,7 +19,8 @@ module Perron
 
         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))
+
+          @collection_caches[collection_name] ||= Cache.new(nil, nil, fingerprinted(collection_name))
         end
 
         def self.clear_cache!(collection_name)
@@ -26,12 +28,13 @@ module Perron
         end
 
         def self.stale?(collection_name)
-          @collection_caches[collection_name]&.fingerprint != content_fingerprint(collection_name)
+          @collection_caches[collection_name]&.fingerprint != fingerprinted(collection_name)
         end
 
-        def self.content_fingerprint(collection_name)
+        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
 
@@ -52,55 +55,53 @@ module Perron
 
         private
 
-        def resources = @cache.resources ||= @collection.resources
+        def resources
+          @cache.resources ||= @collection.resources
+        end
 
-        def similarity_matrix = @cache.similarity_matrix ||= build_similarity_matrix
+        def similarity_matrix
+          @cache.similarity_matrix ||= build_similarity_matrix
+        end
 
         def build_similarity_matrix
           vectors = resources.to_h { [it.slug, normalize(tfidf_vector_for(it))] }
-          matrix = Hash.new { |h, k| h[k] = {} }
 
-          slugs = vectors.keys
-          slugs.each_with_index do |slug_a, i|
-            next if vectors[slug_a].empty?
+          Hash.new { |hash, key| hash[key] = {} }.tap do |matrix|
+            slugs = vectors.keys
+
+            slugs.each_with_index do |slug_a, index|
+              next if vectors[slug_a].empty?
 
-            slugs[(i + 1)..].each do |slug_b|
-              next if vectors[slug_b].empty?
+              slugs[(index + 1)..].each do |slug_b|
+                next if vectors[slug_b].empty?
 
-              score = dot_product(vectors[slug_a], vectors[slug_b])
-              matrix[slug_a][slug_b] = score
-              matrix[slug_b][slug_a] = score
+                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
-
-          matrix
-        end
-
-        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
 
         def normalize(vector)
-          return {} if vector.empty?
-
           magnitude = Math.sqrt(vector.values.sum { it**2 })
-          return {} if magnitude.zero?
+          return {} if vector.empty? || magnitude.zero?
 
           vector.transform_values { it / magnitude }
         end
 
         def tfidf_vector_for(resource)
-          tokens = tokenize(resource)
+          tokens = tokenized(resource)
           return {} if tokens.empty?
 
           token_count = tokens.size.to_f
-
           tokens.tally.to_h { |term, count| [term, (count / token_count) * inverse_document_frequency[term]] }
         end
 
-        def tokenize(resource)
+        def dot_product(vector_a, vector_b)
+          vector_a.sum { |term, value| value * (vector_b[term] || 0) }
+        end
+
+        def tokenized(resource)
           return [] if resource.content.blank?
 
           resource.content.gsub(/<[^>]*>/, " ").downcase.scan(/\w+/).reject { StopWords.all.include?(it) || it.length < 3 }
@@ -108,11 +109,11 @@ module Perron
 
         def inverse_document_frequency
           @inverse_document_frequency ||= begin
-            doc_frequency = Hash.new(0)
-            resources.each { tokenize(it).uniq.each { doc_frequency[it] += 1 } }
+            document_frequency = Hash.new(0)
+            resources.each { tokenized(it).uniq.each { document_frequency[it] += 1 } }
 
             total = resources.size.to_f
-            doc_frequency.transform_values { Math.log(total / (1 + it)) }
+            document_frequency.transform_values { Math.log(total / (1 + it)) }
           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::DataSource.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::DataSource.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.rb

@@ -17,6 +17,7 @@ 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
@@ -34,6 +35,7 @@ module Perron
     include Previewable
     include Scopes
     include Sweeper
+    include Adjacency
     include TableOfContent
 
     attr_reader :file_path, :id

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"