wax_tasks 0.2.0 → 0.3.0

data/lib/wax_tasks/task_runner.rb

@@ -0,0 +1,132 @@
+module WaxTasks
+  # Class for running the Rake tasks in ./tasks
+  # TaskRunner is responsible for loading and parsing the site config
+  # from `_config.yml`, which can be overridden with .override(opts)
+  #
+  # @attr site [Hash] main variables from site config normalized + symbolized
+  class TaskRunner
+    attr_reader :site
+
+    # Creates a new TaskRunner with a config hash or default config file
+    #
+    # @param env    [String]  test/prod. only affects Branch module
+    # @param config [Hash]    optional hash, should mirror a parsed _config.yml
+    # @example give a custom config
+    #   config = {
+    #     title:        'custom title',
+    #     url:          'custom.url',
+    #     collections:  {...}
+    #   }
+    #   WaxTasks::TaskRunner.new(config)
+    # @example use default config from file
+    #   WaxTasks::TaskRunner.new
+    def initialize(config = {}, env = 'prod')
+      config = YAML.load_file(DEFAULT_CONFIG).symbolize_keys if config.empty?
+      @site = {
+        env:              env,
+        title:            config.fetch(:title, ''),
+        url:              config.fetch(:url, ''),
+        baseurl:          config.fetch(:baseurl, ''),
+        repo_name:        config.fetch(:repo_name, ''),
+        source_dir:       config.fetch(:source, nil),
+        collections_dir:  config.fetch(:collections_dir, nil),
+        collections:      config.fetch(:collections, {}),
+        js:               config.fetch(:js, false),
+        permalink:        Utils.construct_permalink(config)
+      }
+    rescue StandardError => e
+      raise Error::InvalidSiteConfig, "Could not load _config.yml. => #{e}"
+    end
+
+    # Overrides a specific part of @site
+    #
+    # @param opts [Hash] part of the site config to be overwritten
+    # @example override title + url
+    #   runner = WaxTasks::TaskRunner.new
+    #   runner.override({ title: 'my new title', url: 'my-new.url' })
+    def override(opts)
+      opts.each { |k, v| @site[k] = v }
+      @site[:permalink] = Utils.construct_permalink(opts)
+      self
+    end
+
+    # Given an array of command line arguments `args`,
+    # creates a PagemasterCollection for each and generates markdown
+    # pages from its specified data `source` file
+    #
+    # @param args [Array] the arguments/collection names from wax:pagemaster
+    # @return [Nil]
+    def pagemaster(args)
+      args.each do |name|
+        PagemasterCollection.new(name, @site).generate_pages
+      end
+    end
+
+    # Creates a LunrCollection for each collection
+    # that has lunr_index parameters in the site config
+    # and generates a lunr-index.json file from the collection data
+    #
+    # @param generate_ui [Boolean] whether/not to generate a default lunr UI
+    # @return [Nil]
+    def lunr(generate_ui = false)
+      lunr_collections = Utils.get_lunr_collections(@site)
+      lunr_collections.map! { |name| LunrCollection.new(name, @site) }
+
+      index = LunrIndex.new(lunr_collections)
+      index_path = Utils.make_path(@site[:source_dir], LUNR_INDEX_PATH)
+
+      FileUtils.mkdir_p(File.dirname(index_path))
+      File.open(index_path, 'w') { |f| f.write(index.to_s) }
+
+      ui_path = Utils.make_path(@site[:source_dir], LUNR_UI_PATH)
+      File.open(ui_path, 'w') { |f| f.write(index.default_ui) } if generate_ui
+    end
+
+    # Given an array of command line arguments `args`,
+    # creates a IiifCollection for each and generates iiif
+    # derivative images, manifests, etc. from source image files
+    #
+    # @param args [Array] the arguments/collection names from wax:pagemaster
+    # @return [Nil]
+    def iiif(args)
+      args.each do |name|
+        IiifCollection.new(name, @site).process
+      end
+    end
+
+    # Finds the JS dependencies listed in site config and
+    # writes them to a package.json file
+    # in orderto easily track / monitor / update them
+    #
+    # @return [Nil]
+    def js_package
+      names = []
+      package = {
+        'name'          => site[:title],
+        'version'       => '1.0.0',
+        'dependencies'  => {}
+      }
+      site[:js].each do |dependency|
+        name = dependency[0]
+        names << name
+        version = dependency[1]['version']
+        package['dependencies'][name] = '^' + version
+      end
+      package
+    end
+
+    # Constructs a TravisBranch or LocalBranch object
+    # with appropriate Git credentials and pushes
+    # the compiled Jekyll site to the target GitHub branch
+    #
+    # @param target [String] the name of the Git branch to deploy to
+    # @return [Nil]
+    def push_branch(target)
+      if ENV.fetch('CI', false)
+        TravisBranch.new(self.site, target).push
+      else
+        LocalBranch.new(self.site, target).push
+      end
+    end
+  end
+end

data/lib/wax_tasks/utils.rb

@@ -0,0 +1,194 @@
+module WaxTasks
+  # Utility helper methods
+  module Utils
+    # Contructs permalink extension from site `permalink` variable
+    #
+    # @param site [Hash] the site config
+    # @return [String] the end of the permalink, either '/' or '.html'
+    def self.construct_permalink(site)
+      case site.fetch(:permalink, false)
+      when 'pretty' || '/'
+        '/'
+      else
+        '.html'
+      end
+    end
+
+    # Checks and asserts presence of `pid` value for each item
+    #
+    # @param  data [Array] array of hashes each representing a collection item
+    # @return [Array] same data unless a an item is missing the key `pid`
+    # @raise WaxTasks::Error::MissingPid
+    def self.assert_pids(data)
+      data.each_with_index { |d, i| raise Error::MissingPid, "Collection #{@name} is missing pid for item #{i}." unless d.key? 'pid' }
+      data
+    end
+
+    # Checks and asserts uniqueness of `pid` value for each item
+    #
+    # @param  data [Array] array of hashes each representing a collection item
+    # @return [Array] same data unless an item has non-unique value for `pid`
+    # @raise WaxTasks::Error::NonUniquePid
+    def self.assert_unique(data)
+      pids = data.map { |d| d['pid'] }
+      not_unique = pids.select { |p| pids.count(p) > 1 }.uniq! || []
+      raise Error::NonUniquePid, "#{@name} has the following nonunique pids:\n#{not_unique}" unless not_unique.empty?
+      data
+    end
+
+    # Checks that a CSV file is valid
+    #
+    # @param  source [String] path to CSV file
+    # @return [Array] validated CSV data as an Array of Hashes
+    # @raise  WaxTasks::Error::InvalidCSV
+    def self.validate_csv(source)
+      CSV.read(source, headers: true).map(&:to_hash)
+    rescue StandardError => e
+      raise Error::InvalidCSV, " #{e}"
+    end
+
+    # Checks that a JSON file is valid
+    #
+    # @param  source [String] path to JSON file
+    # @return [Array] validated JSON data as an Array of Hashes
+    # @raise  WaxTasks::Error::InvalidJSON
+    def self.validate_json(source)
+      file = File.read(source)
+      JSON.parse(file)
+    rescue StandardError => e
+      raise Error::InvalidJSON, " #{e}"
+    end
+
+    # Checks that a YAML file is valid
+    #
+    # @param  source [String] path to YAML file
+    # @return [Array] validated YAML data as an Array of Hashes
+    # @raise  WaxTasks::Error::InvalidYAML
+    def self.validate_yaml(source)
+      YAML.load_file(source)
+    rescue StandardError => e
+      raise WaxTasks::Error::InvalidYAML, " #{e}"
+    end
+
+    # Creates a file path valid file path with empty strings and
+    # null values dropped
+    #
+    # @param  args [Array] items to concatenate in path
+    # @return [String] file path
+    def self.make_path(*args)
+      args.compact.reject(&:empty?).join('/')
+    end
+
+    # Finds collections in site config where `lunr_index` is enabled
+    #
+    # @param  site [Hash] the site config
+    # @return [Array] a list of collection names
+    # @raise WaxTasks::Error::NoLunrCollections
+    def self.get_lunr_collections(site)
+      to_index = site[:collections].find_all { |c| c[1].key?('lunr_index') }
+      raise Error::NoLunrCollections, 'There are no lunr collections to index.' if to_index.nil?
+      to_index.map { |c| c[0] }
+    end
+  end
+end
+
+# Monkey-patched String class
+class String
+  # Removes YAML front matter from a string
+  # @return [String]
+  def remove_yaml
+    self.gsub!(/\A---(.|\n)*?---/, '')
+  end
+
+  # Cleans YAML front matter + markdown pages for lunr indexing
+  # @return [String]
+  def html_strip
+    self.gsub!(/\A---(.|\n)*?---/, '') # remove yaml front matter
+    self.gsub!(/{%(.*)%}/, '') # remove functional liquid
+    self.gsub!(%r{<\/?[^>]*>}, '') # remove html
+    self.gsub!('\\n', '') # remove newlines
+    self.gsub!(/\s+/, ' ') # remove extra space
+    self.tr!('"', "'") # replace double quotes with single
+    self
+  end
+
+  # Normalizes accent marks/diacritics for Lunr indexing
+  # @return [String]
+  def remove_diacritics
+    to_replace  = 'ÀÁÂÃÄÅàáâãäåĀāĂ㥹ÇçĆćĈĉĊċČčÐðĎďĐđÈÉÊËèéêëĒēĔĕĖėĘęĚěĜĝĞğĠġĢģĤĥĦħÌÍÎÏìíîïĨĩĪīĬĭĮįİıĴĵĶķĸĹĺĻļĽľĿŀŁłÑñŃńŅņŇňʼnŊŋÒÓÔÕÖØòóôõöøŌōŎŏŐőŔŕŖŗŘřŚśŜŝŞşŠšſŢţŤťŦŧÙÚÛÜùúûüŨũŪūŬŭŮůŰűŲųŴŵÝýÿŶŷŸŹźŻżŽž'
+    replaced_by = 'AAAAAAaaaaaaAaAaAaCcCcCcCcCcDdDdDdEEEEeeeeEeEeEeEeEeGgGgGgGgHhHhIIIIiiiiIiIiIiIiIiJjKkkLlLlLlLlLlNnNnNnNnnNnOOOOOOooooooOoOoOoRrRrRrSsSsSsSssTtTtTtUUUUuuuuUuUuUuUuUuUuWwYyyYyYZzZzZz'
+    self.tr(to_replace, replaced_by)
+  end
+
+  # Converts string to snake case and swaps out special chars
+  # @return [String]
+  def slug
+    self.downcase.tr(' ', '_').gsub(/[^\w-]/, '')
+  end
+
+  # Normalizes string without diacritics for lunr indexing
+  # @return [String]
+  def normalize
+    self.remove_diacritics
+  end
+
+  # Colorizes console output to magenta (errors)
+  # @return [String]
+  def magenta
+    "\e[35m#{self}\e[0m"
+  end
+
+  # Colorizes console output to cyan (messages)
+  # @return [String]
+  def cyan
+    "\e[36m#{self}\e[0m"
+  end
+
+  # Colorizes console output to orange (warnings)
+  # @return [String]
+  def orange
+    "\e[33m#{self}\e[0m"
+  end
+end
+
+# Monkey-patched Array class
+class Array
+  # Normalizes an array as a string or array of hashes
+  # without diacritics for lunr indexing
+  # @return [Hash || String] description
+  def normalize
+    if self.first.is_a? Hash
+      self
+    else
+      self.join(', ').remove_diacritics
+    end
+  end
+end
+
+# Monkey-patched Hash class
+class Hash
+  # Normalizes hash as itself for lunr indexing
+  # @return [Hash]
+  def normalize
+    self
+  end
+
+  # Converts hash keys to symbols
+  # @return [Hash]
+  def symbolize_keys
+    hash = self
+    hash.clone.each_key do |key|
+      hash[key.to_sym || key] = hash.delete(key)
+    end
+    hash
+  end
+end
+
+# Monkey-patched Integer class
+class Integer
+  # Normalizes integer as a string for lunr indexing
+  # @return [String]
+  def normalize
+    self.to_s
+  end
+end

data/lib/wax_tasks.rb

@@ -1,27 +1,35 @@
-require 'yaml'
+require_relative 'wax_tasks/branch'
+require_relative 'wax_tasks/collection'
+require_relative 'wax_tasks/error'
+require_relative 'wax_tasks/iiif_collection'
+require_relative 'wax_tasks/lunr_collection'
+require_relative 'wax_tasks/lunr_index'
+require_relative 'wax_tasks/pagemaster_collection'
+require_relative 'wax_tasks/task_runner'
+require_relative 'wax_tasks/utils'
 
-require_relative 'wax/branch'
-require_relative 'wax/collection'
-require_relative 'wax/index'
-require_relative 'wax/iiif_collection'
-require_relative 'wax/lunr_collection'
-require_relative 'wax/pagemaster_collection'
-require_relative 'wax/utilities'
-
-# document
+# The WaxTasks module powers the Rake tasks in `./tasks`, including:
+#
+# wax:pagemaster  :: generate collection md pages from csv, json, or yaml file
+# wax:lunr        :: build lunr search index (with default UI if UI=true)
+# wax:iiif        :: generate iiif derivatives from local image files
+# wax:jspackage   :: write a simple package.json for monitoring js dependencies
+# wax:push        :: push compiled Jekyll site to git branch
+# wax:test        :: run htmlproofer, rspec if .rspec file exists
+#
+# Tasks are run by a WaxTasks::TaskRunner object which is resposible
+# for reading in site config from `_config.yml`
 module WaxTasks
-  def self.site_config
-    site_config = YAML.load_file('./_config.yml')
-    s_conf = {
-      title:       site_config.fetch('title', ''),
-      url:         site_config.fetch('url', ''),
-      baseurl:     site_config.fetch('baseurl', ''),
-      permalink:   site_config.fetch('permalink', false),
-      c_dir:       site_config.fetch('collections_dir', false),
-      collections: site_config.fetch('collections', false),
-      js:          site_config.fetch('js', false)
-    }
-    s_conf[:permalink] = s_conf[:permalink] == 'pretty' ? '/' : '.html'
-    s_conf
-  end
+  # ----------
+  # CONSTANTS
+  # ----------
+
+  # @return [String] The path to load Jekyll site config
+  DEFAULT_CONFIG  = '_config.yml'.freeze
+  # @return [String] The path to write WaxTasks::LunrIndex
+  LUNR_INDEX_PATH = 'js/lunr_index.json'.freeze
+  # @return [String] The path to write default LunrUI
+  LUNR_UI_PATH    = 'js/lunr_ui.js'.freeze
+  # @return [String] The path to the compiled Jekyll site
+  SITE_DIR        = './_site'.freeze
 end

data/spec/setup.rb

@@ -0,0 +1,38 @@
+require 'fileutils'
+
+#constants
+ROOT    = `pwd`.strip.freeze
+SAMPLE  = "#{ROOT}/spec/sample_site".freeze
+BUILD   = "#{ROOT}/build".freeze
+
+# helper methods
+def quiet_stdout
+  if QUIET
+    begin
+      orig_stderr = $stderr.clone
+      orig_stdout = $stdout.clone
+      $stderr.reopen File.new('/dev/null', 'w')
+      $stdout.reopen File.new('/dev/null', 'w')
+      retval = yield
+    rescue StandardError => e
+      $stdout.reopen orig_stdout
+      $stderr.reopen orig_stderr
+      raise e
+    ensure
+      $stdout.reopen orig_stdout
+      $stderr.reopen orig_stderr
+    end
+    retval
+  else
+    yield
+  end
+end
+
+module WaxTasks::Test
+  def self.reset
+    Dir.chdir(ROOT)
+    FileUtils.rm_r(BUILD) if File.directory?(BUILD)
+    FileUtils.copy_entry SAMPLE, BUILD
+    Dir.chdir(BUILD)
+  end
+end

data/spec/spec_helper.rb

@@ -1,47 +1,37 @@
 # toggle stdout/stderr verbosity
-QUIET = true
+#
+# run $ DEBUG=true bundle exec rspec for verbose output
+# run $ bundle exec rspec for sparse output
+case ENV['DEBUG']
+when 'true' then QUIET = false
+else QUIET = true
+end
 
 # use codecov + add requirements
 require 'simplecov'
 SimpleCov.start do
   add_filter 'spec'
-  add_filter 'utilities'
   add_filter 'branch'
 end
 
-require_relative './../lib/wax_tasks'
-require_relative 'fake/site'
-
-# setup
-quiet_stdout { Fake.site }
-
-# constants
-SITE_CONFIG = WaxTasks.site_config
-ARGS = SITE_CONFIG[:collections].map { |c| c[0] }
-PM_COLLECTIONS = quiet_stdout { ARGS.map { |a| PagemasterCollection.new(a) } }
-IIIF_COLLECTIONS = ARGS.map { |a| IiifCollection.new(a) }
-
-# run specs
-require_relative 'pagemaster'
-require_relative 'lunr'
-require_relative 'iiif'
-
-describe 'jekyll' do
-  it 'builds successfully' do
-    quiet_stdout { Bundler.with_clean_env { system('bundle exec jekyll build') } }
-  end
-end
-
-describe 'wax:jspackage' do
-  it 'writes a package.json file' do
-    quiet_stdout { system('bundle exec rake wax:jspackage') }
-    package = File.open('package.json', 'r').read
-    expect(package.length > 90)
-  end
+# load + setup
+require 'wax_tasks'
+require 'setup'
+
+# provide shared context for tests
+shared_context 'shared', :shared_context => :metadata do
+  let(:task_runner) { WaxTasks::TaskRunner.new }
+  let(:default_site) { task_runner.site }
+  let(:args) { default_site[:collections].map{ |c| c[0] } }
+  let(:index_path) { 'js/lunr_index.json' }
+  let(:ui_path) { 'js/lunr_ui.js'}
 end
 
-describe 'wax:test' do
-  it 'passes html-proofer' do
-    quiet_stdout { system('bundle exec rake wax:test') }
-  end
-end
+# run tests in a more intuitive order
+require 'tests/tasks_spec'
+require 'tests/task_runner_spec'
+require 'tests/utils_spec'
+require 'tests/pagemaster_collection_spec'
+require 'tests/lunr_collection_spec'
+require 'tests/iiif_collection_spec'
+require 'tests/branch_spec'

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: wax_tasks
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marii Nyrop
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-12 00:00:00.000000000 Z
+date: 2018-07-26 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: colorize
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: html-proofer
   requirement: !ruby/object:Gem::Requirement
@@ -94,20 +80,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1'
-- !ruby/object:Gem::Dependency
-  name: faker
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -122,7 +94,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3'
-description: Rake tasks for minimal iiif exhibition sites with Jekyll.
+description: Rake tasks for minimal exhibition sites with Jekyll Wax.
 email:
 - m.nyrop@columbia.edu
 executables: []
@@ -130,23 +102,23 @@ extensions: []
 extra_rdoc_files: []
 files:
 - Gemfile
-- lib/wax/branch.rb
-- lib/wax/collection.rb
-- lib/wax/iiif_collection.rb
-- lib/wax/index.rb
-- lib/wax/lunr_collection.rb
-- lib/wax/pagemaster_collection.rb
-- lib/wax/tasks/iiif.rake
-- lib/wax/tasks/jspackage.rake
-- lib/wax/tasks/lunr.rake
-- lib/wax/tasks/pagemaster.rake
-- lib/wax/tasks/push.rake
-- lib/wax/tasks/test.rake
-- lib/wax/utilities.rb
+- lib/tasks/iiif.rake
+- lib/tasks/jspackage.rake
+- lib/tasks/lunr.rake
+- lib/tasks/pagemaster.rake
+- lib/tasks/push.rake
+- lib/tasks/test.rake
 - lib/wax_tasks.rb
-- spec/iiif.rb
-- spec/lunr.rb
-- spec/pagemaster.rb
+- lib/wax_tasks/branch.rb
+- lib/wax_tasks/collection.rb
+- lib/wax_tasks/error.rb
+- lib/wax_tasks/iiif_collection.rb
+- lib/wax_tasks/lunr_collection.rb
+- lib/wax_tasks/lunr_index.rb
+- lib/wax_tasks/pagemaster_collection.rb
+- lib/wax_tasks/task_runner.rb
+- lib/wax_tasks/utils.rb
+- spec/setup.rb
 - spec/spec_helper.rb
 homepage: https://github.com/minicomp/wax_tasks
 licenses:
@@ -172,9 +144,7 @@ rubyforge_project:
 rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
-summary: Rake tasks for minimal exhibitions.
+summary: Rake tasks for minimal exhibition sites with Jekyll Wax.
 test_files:
+- spec/setup.rb
 - spec/spec_helper.rb
-- spec/iiif.rb
-- spec/pagemaster.rb
-- spec/lunr.rb

data/lib/wax/branch.rb

@@ -1,70 +0,0 @@
-require 'colorize'
-require 'jekyll'
-require 'tmpdir'
-require 'time'
-require 'yaml'
-
-# methods for building/pushing git branches
-module Branch
-  def build(baseurl)
-    FileUtils.rm_rf('_site')
-    opts = {
-      source: '.',
-      destination: '_site',
-      config: '_config.yml',
-      baseurl:  baseurl,
-      verbose: true
-    }
-    Jekyll::Site.new(Jekyll.configuration(opts)).process
-  end
-
-  def push
-    abort "Cannot find _site.".magenta unless Dir.exist? '_site'
-    Dir.chdir('./_site')
-    system 'git init && git add .'
-    system "git commit -m '#{@commit_msg}'"
-    system "git remote add origin #{@origin}"
-    system "git push origin master:refs/heads/#{TARGET} --force"
-  end
-end
-
-# configure git branches from travis info
-class TravisBranch
-  include Branch
-
-  def initialize
-    @repo_slug  = ENV['TRAVIS_REPO_SLUG']
-    @user       = @repo_slug.split('/')[0]
-    @repo_name  = '1' + @repo_slug.split('/')[1]
-    @token      = ENV['ACCESS_TOKEN']
-    @commit_msg = "Site updated via #{ENV['TRAVIS_COMMIT']} at #{Time.now.utc}"
-    @origin     = "https://#{@user}:#{@token}@github.com/#{@repo_slug}.git"
-
-    puts "Deploying to #{TARGET} branch from Travis as #{@user}.".cyan
-  end
-
-  def build_gh_site
-    abort 'You must add the gh-baseurl to config.' if @repo_name.nil?
-    build(@repo_name)
-  end
-end
-
-# configure git branches from local info
-class LocalBranch
-  include Branch
-
-  attr_reader :origin, :commit_msg
-
-  def initialize
-    @origin     = `git config --get remote.origin.url`
-    @commit_msg = "Site updated via local task at #{Time.now.utc}"
-    puts "Deploying to #{TARGET} branch from local task.".cyan
-  end
-
-  def build_gh_site
-    abort "Cannot load config.".magenta unless CONFIG
-    baseurl = CONFIG.fetch('gh-baseurl', false)
-    abort "You must add the gh-baseurl to config.".magenta unless baseurl
-    build(baseurl)
-  end
-end