lifer 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5891938dbf0269f6cf30b14cd14130025b2214e0b03b6c756d48efa1abf8ae3
-  data.tar.gz: a6bb29832ac1e2ccde939d17f6c84643c5d8f3544d0cda7f407a696d642836e7
+  metadata.gz: 5b5555d8af73f17e139a069f5b18b104c7938cf8089525ecd3d27b703d388d64
+  data.tar.gz: 83ed1f8052bb3f7e241276ca2e7354f870429e5fd5ff5a5a2a97c36d1d756c4c
 SHA512:
-  metadata.gz: 6cd12ec2588d1afc192352219a98e04672ce721069160bc5b3f0db5e2c91998a156318d30ee7a3299d062f32127b0cf9cc9d7eea7ece320212627c3e27344d91
-  data.tar.gz: 1506e4a3bf8957dce6dbacccf25d75a52edf710c886a8955b979dede89b698dfc8f0a8dd1571fa6275ad8737ad0cdc2e9897503b16bb848bcaef2027ddfb8fcf
+  metadata.gz: b79197172aedc215a7d1acab9665406e5065b0aa32451ca5b76d89742021660f87c6ab6366edb581ab2477ad400a3a741468480d5a428cab1113544e11485c3a
+  data.tar.gz: e09e4484fb63f9b093b7a03ddff94ee49e0dc7c3bca1fe68e316540c9a02f4561f215f7c32bb77e842c83d1e63f30d57d252569218b8d2eddf2aa8823ce06d15

data/.github/workflows/main.yml

@@ -11,7 +11,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.1.2
+        ruby-version: 3.3.4
         bundler-cache: true
     - name: Run the default task
       run: bundle exec rake

data/.gitignore

@@ -11,3 +11,4 @@ lifer*.gem
 
 # Temp files.
 /tmp/
+/doc/

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+## v0.3.0
+
+This version marks the first version of Lifer that is kind of usable. The README
+currently describes the big picture best. But I can that as of this version,
+I've documented all of the public interfaces and added a good number of `FIXME`
+comments to indicate functionality that _works_ but isn't quite where I want it
+to be long term.
+
+To manually test everything, I took my legacy Jekyll-based static site and
+successfully ported it to Lifer.
+
+The biggest thorn in my side is the Liquid rendering implementation. It works,
+but the amount of trouble it was, and the not-very-serious way Liquid reports
+rendering issues after build time, makes me think that this will come back to
+haunt me.
+
+Special thanks to [Chris][1] for helping me with some loading issues and
+[Madeline][2] for helping me diagnose some disgusting Liquid template rendering
+issues.
+
+[1]: https://github.com/forkata
+[2]: https://github.com/madelinecollier
+
+## v0.2.0
+
+![It's a living](lib/lifer/templates/its-a-living.png)

data/Gemfile

@@ -4,5 +4,14 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "bump"
+
+gem "capybara"
+
+gem "debug", ">= 1.0.0"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
+gem "parallel_tests"
+gem "ruby-lsp"
+
+gem "yard"

data/Gemfile.lock

@@ -1,48 +1,133 @@
 PATH
   remote: .
   specs:
-    lifer (0.1.0)
+    lifer (0.3.0)
+      i18n (< 2)
       kramdown (~> 2.4)
+      liquid (< 6)
+      listen (< 4)
+      puma (< 7)
+      rack (< 4)
+      rss
 
 GEM
   remote: https://rubygems.org/
   specs:
-    debug (1.6.2)
-      irb (>= 1.3.6)
-      reline (>= 0.3.1)
-    diff-lcs (1.5.0)
-    io-console (0.5.11)
-    irb (1.4.1)
-      reline (>= 0.3.0)
-    kramdown (2.4.0)
-      rexml
-    rake (13.0.6)
-    reline (0.3.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    bigdecimal (3.1.9)
+    bump (0.10.0)
+    capybara (3.40.0)
+      addressable
+      matrix
+      mini_mime (>= 0.1.3)
+      nokogiri (~> 1.11)
+      rack (>= 1.6.0)
+      rack-test (>= 0.6.3)
+      regexp_parser (>= 1.5, < 3.0)
+      xpath (~> 3.2)
+    concurrent-ruby (1.3.4)
+    debug (1.9.2)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.5.1)
+    ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86_64-darwin)
+    ffi (1.17.1-x86_64-linux-gnu)
+    i18n (1.14.6)
+      concurrent-ruby (~> 1.0)
+    io-console (0.7.2)
+    irb (1.14.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
+    language_server-protocol (3.17.0.3)
+    liquid (5.6.0)
+      bigdecimal
+      strscan
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.6.1)
+    matrix (0.4.2)
+    mini_mime (1.1.5)
+    nio4r (2.7.4)
+    nokogiri (1.16.7-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.7-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.16.7-x86_64-linux)
+      racc (~> 1.4)
+    parallel (1.26.3)
+    parallel_tests (4.7.2)
+      parallel
+    prism (1.0.0)
+    psych (5.1.2)
+      stringio
+    public_suffix (6.0.1)
+    puma (6.5.0)
+      nio4r (~> 2.0)
+    racc (1.8.1)
+    rack (3.1.7)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rbs (3.5.3)
+      logger
+    rdoc (6.7.0)
+      psych (>= 4.0.0)
+    regexp_parser (2.9.2)
+    reline (0.5.10)
       io-console (~> 0.5)
-    rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rexml (3.4.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.1)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.1)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rss (0.3.1)
+      rexml
+    ruby-lsp (0.17.17)
+      language_server-protocol (~> 3.17.0)
+      prism (~> 1.0)
+      rbs (>= 3, < 4)
+      sorbet-runtime (>= 0.5.10782)
+    sorbet-runtime (0.5.11558)
+    stringio (3.1.1)
+    strscan (3.1.2)
+    xpath (3.2.0)
+      nokogiri (~> 1.8)
+    yard (0.9.37)
 
 PLATFORMS
+  arm64-darwin-22
   x86_64-darwin-21
+  x86_64-darwin-22
   x86_64-linux
 
 DEPENDENCIES
-  debug
+  bump
+  capybara
+  debug (>= 1.0.0)
   lifer!
+  nokogiri
+  parallel_tests
   rake (~> 13.0)
   rspec (~> 3.0)
+  ruby-lsp
+  yard
 
 BUNDLED WITH
    2.3.21

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright 2024 benjamin wil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,35 +1,100 @@
 # Lifer
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/lifer`. To experiment with that code, run `bin/console` for an interactive prompt.
+Lifer is an extensible static site generator. Out of the box, it provides a
+classic static site generation experience, complete with RSS feeds, ERB template
+rendering, and Liquid template rendering. Unlike other Ruby-based static site
+generators, Lifer encourages you to bring your own asset pipeline and configure
+it as a pre-build step.
 
-TODO: Delete this and the text above, and describe your gem
+_Lifer is currently in pre-release. Features are incomplete. Your mileage may
+vary._
+
+**What's with the name?** Lifer aims to be easy to maintain for the lifetime of
+your static site by requiring few dependencies and being very extensible by the
+end user. There is no need for plugins in the form of separate Ruby gems. The
+generator should also "breathe life" into your project because it's so easy to
+use (🤞).
+
+## Features
+
+Here's a short overview of Lifer's flagship features.
+
+### Bring your own asset pipeline
+
+Whether you want to compile assets with Ruby-based tools, JavaScript-based
+tools, or other tools, Lifer is okay with that. As long as those tools come with
+a commandline interface, Lifer can shell out to those tools as a prebuild step.
+
+The tradeoff here is that your templates will not be asset aware, meaning asset
+fingerprinting and complex asset locating isn't really possible at this time. If
+you need features like that, consider other static site generators or consider
+*not* using a static site generator.
+
+### Collections and selections
+
+If you have multiple collections of entries that must be output in different
+ways, Lifer can help you do this. While every entry can only belong to a single
+collection, you can create your own "selections" filter to group entries across
+collections.
+
+### Extensibility
+
+Lifer autoloads any Ruby files included in the root of your project
+automatically. This lets you specify your own custom output builders, feed
+formats, and meta-collections of entries.
+
+### Development server
+
+Need to preview your static site before your build it on your production server?
+No problem. Just use the Lifer commandline interface to start a development
+server at `http://localhost:9292`:
+
+    $ lifer serve
+
+The development server is not very sophisticated and can still be improved. But
+for previewing new entries? It works just fine.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+_This installation guide assumes you already have Ruby 3 installed on your
+system._
+
+I recommend installing Lifer via Bundler. In the root directory of your static
+site source, add a Gemfile if one doesn't exist already:
+
+    $ bundle init
+
+In the Gemfile, add the `lifer` gem:
 
 ```ruby
-gem 'lifer'
+gem "lifer", "<= 1"
 ```
 
 And then execute:
 
     $ bundle install
 
-Or install it yourself as:
-
-    $ gem install lifer
+## Development
 
-## Usage
+_This development guide assumes you already have Ruby 3 installed on your
+system._
 
-TODO: Write usage instructions here
+Clone this repository, install dependencies via Bundler, and ensure the test
+suite can run on your machine:
 
-## Development
+    $ git clone https://github.com/benjaminwil/lifer lifer
+    $ cd lifer
+    $ bundle install
+    $ bundle exec rspec
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Contributing
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+I'm not currently accepting unsolicited contributions to Lifer. I'm still
+figuring out what the shape of this project is.
 
-## Contributing
+If you encounter bugs, please open an issue.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lifer.
+If you have ideas for improving existing functionality or adding *missing*
+functionality, please open an issue. Maybe there is room for you to contribute,
+but I don't want you to waste your time preparing a merge request that I won't
+accept.

data/Rakefile

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require "parallel_tests/tasks"
 
-RSpec::Core::RakeTask.new(:spec)
-
-task default: :spec
+task default: :"parallel:spec"

data/bin/lifer

@@ -1,6 +1,8 @@
 #!/usr/bin/env -S ruby -Eutf-8
 
 require "bundler/setup"
-require_relative "../lib/lifer"
 
-Lifer.build
+require "lifer"
+require "lifer/cli"
+
+Lifer::CLI.start!

data/lib/lifer/brain.rb

@@ -1,45 +1,195 @@
+require "fileutils"
+
+require_relative "config"
+
+# The brain is the object that keeps track of all essential information about
+# the current Lifer project. Usually this information will be consumed via the
+# `Lifer` module methods.
+#
 class Lifer::Brain
+  # The default configuration file URI.
+  #
+  DEFAULT_CONFIG_FILE_URI = ".config/lifer.yaml"
+
   attr_reader :root
 
   class << self
-    def init(root: Dir.pwd)
-      new(root: root)
-    end
+    # The preferred initializer for the single `Lifer::Brain` object that
+    # represents the user's Lifer project.
+    #
+    # @param root [String] The root Lifer project directory.
+    # @param config_file [String] A path to the correct Lifer config file. If
+    #   left empty, the brain uses the one at the default path or the one
+    #   bundled with the gem.
+    # @return [Lifer::Brain] The brain object for the current Lifer project.
+    def init(root: Dir.pwd, config_file: nil) = new(root:, config_file:)
   end
 
-  def build!
-    Lifer::Builder::HTML.execute(root: root)
+  # Destroy any existing build output and then build the Lifer project with all
+  # configured `Lifer::Builder`s.
+  #
+  # @param environment [Symbol] The current Lifer environment.
+  # @return [void] This builds the Lifer site to the configured output
+  #   directory.
+  def build!(environment: :build)
+    brainwash!
+
+    prebuild_steps =
+      case setting(:global, :prebuild)
+      when Array, NilClass then setting(:global, :prebuild)
+      when Hash then setting(:global, :prebuild, environment)
+      end
+
+    builder_list =
+      case setting(:global, :build)
+      when Array, NilClass then setting(:global, :build)
+      when Hash then setting(:global, :build, environment)
+      end
+
+    Lifer::Builder.prebuild!(*prebuild_steps, root:)
+    Lifer::Builder.build!(*builder_list, root:)
   end
 
+  # Returns all collections and selections within the Lifer root.
+  #
+  # Collections only exist if they're explicitly configured in a configuration
+  # file and they match a subdirectory within the root.
+  #
+  # Selections, on the other hand, reorganize entries from literal collections.
+  # For example, a user could collect all of their entries that were authored
+  # by Harry B. Cutler.
+  #
+  # Every Lifer build contains at least one collection. (That collection is
+  # `:root`.)
+  #
+  # @return [Array<Lifer::Collection>] All the collections for the current Lifer
+  #   project.
   def collections
-    @collections ||=
+    @collections ||= generate_collections + generate_selections
+  end
+
+  # Returns the Lifer project's configuration object.
+  #
+  # @return [Lifer::Config] The Lifer configuration object.
+  def config = (@config ||= Lifer::Config.build file: config_file_location)
+
+  # Returns all entries that have been added to the manifest. If all is working
+  # as intended, this should be every entry ever generated.
+  #
+  # @return [Set<Lifer::Entry>] All entries that currently exist.
+  def entry_manifest = (@entry_manifest ||= Set.new)
+
+  # A manifest of all Lifer project entries.
+  #
+  # @return [Set<Lifer::Entry>] A set of all entries.
+  def manifest = (@manifest ||= Set.new)
+
+  # Returns the build directory for the Lifer project's build output.
+  #
+  # @return [String] The Lifer build directory.
+  def output_directory
+    @output_directory ||=
       begin
-        collection_map =
-          config.collections.map { |collection_name|
-            [collection_name, "#{root}/#{collection_name}"]
-          }.to_h.merge!({root: root})
-
-        collection_map.map { |name, dir|
-          Lifer::Collection.generate(name: name, directory: dir)
-        }
+        dir = "%s/%s" % [root, setting(:global, :output_directory)]
+
+        return Pathname(dir) if Dir.exist? dir
+
+        Dir.mkdir(dir)
+        Pathname(dir)
       end
   end
 
-  def config
-    @config ||= Lifer::Config.build(file: config_file_location)
+  # The user can bring their own Ruby files to be read by Lifer. This ensures
+  # they are loaded before the build starts.
+  #
+  # Note that the user's Bundler path may be in scope, so we need to skip
+  # those Ruby files.
+  #
+  # @return [void]
+  def require_user_provided_ruby_files!
+    return if root.include? Lifer.gem_root
+
+    rb_files = Dir.glob("#{root}/**/*.rb", File::FNM_DOTMATCH)
+
+    if Bundler.bundle_path.to_s.include? root
+      rb_files -=
+        Dir.glob("#{Bundler.bundle_path}/**/*.rb", File::FNM_DOTMATCH)
+    end
+
+    rb_files.each do |rb_file|
+      load rb_file
+    end
   end
 
-  def manifest
-    @manifest ||= Set.new
+  # Given the tree of a setting name, and the setting scope, returns the setting
+  # value. If the in-scope collection does not have a configured setting, this
+  # method will return fallback settings (unless `:strict` is `true`).
+  #
+  # Example usage:
+  #
+  #     setting(:my, :great, :setting)
+  #
+  # @overload setting(path, ..., collection: nil, strict: false)
+  #   @param name [Symbol] A key in the tree to a setting value.
+  #   @param ... [Symbol] Any additional keys in the tree.
+  #   @param collection [Lifer::Collection] The collection to scope the result
+  #     to.
+  #   @param strict [boolean] If true, do not return fallback setting values.
+  #   @return [Array, String] The value of the requested setting.
+  def setting(*name, collection: nil, strict: false)
+    config.setting *name, collection_name: collection&.name, strict: strict
   end
 
   private
 
-  def initialize(root:)
+  attr_reader :config_file_location
+
+  def initialize(root:, config_file:)
     @root = root
+    @config_file_location = build_config_file_location(config_file)
   end
 
-  def config_file_location
-    File.join(root, ".config", "lifer.yaml")
+  def brainwash!
+    FileUtils.rm_r output_directory
+    FileUtils.mkdir_p output_directory
+  end
+
+  def build_config_file_location(path)
+    return File.join(root, DEFAULT_CONFIG_FILE_URI) if path.nil?
+
+    path.start_with?("/") ? path : File.join(root, path)
+  end
+
+  # FIXME:
+  # Do collections work with sub-subdirectories? For example, what if the
+  # configured collection maps to a directory:
+  #
+  #     subdirectory_one/sub_subdirectory_one
+  #
+  # @return [Set<Lifer::Collection>]
+  def generate_collections
+    config.collectionables
+      .map { |collection_name| [collection_name, "#{root}/#{collection_name}"] }
+      .to_h
+      .merge!({root: root})
+      .map { |collection_name, directory|
+        Lifer::Collection.generate name: collection_name, directory: directory
+      }
+      .to_set
+  end
+
+  # @private
+  # Requires user-provided selection classes (classes that subclass
+  # `Lifer::Selection` and implement an `#entries` method) so that users can
+  # bring their own pseudo-collections of entries.
+  #
+  # @return [Set<Lifer::Selection>]
+  def generate_selections
+    return [] if config.file.to_s.include? Lifer.gem_root
+
+    config.setting(:selections).map { |selection_name|
+      klass = Lifer::Utilities.classify selection_name
+      klass.generate
+    }.to_set
   end
 end