palimpsest 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: bb9471fad6a53da1e1cc97a04c7883e81bfa6756
+  data.tar.gz: ad2694a1fecbbe589e1bd2287d003398c0d4408c
+SHA512:
+  metadata.gz: 44c0455bd09f9084fbb2b90cd24c97f833ccb2e70594788a0632846955db6a8dd23b43425ac4e68a740a1c0c0a5c9b8c5c05e91bc831c50a4fdaf6cc413aa2fd
+  data.tar.gz: 6e9e38fa4cead06576012f74eda7cc94baf115578be4fd282a810ae7586d13dcbe19a0ccdc595e76cd4bf7ea51bd520a156023f6ad69228eb09a7264fd759431

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.kateproject.d/
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.kateproject

@@ -0,0 +1,4 @@
+{
+  "name"  : "palimpsest",
+  "files" : [ { "git" : 1 } ]
+}

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm: [ 2.0.0 ]
+script: rspec

data/.yardopts

@@ -0,0 +1,7 @@
+--markup-provider=redcarpet
+--markup=markdown
+lib/**/*.rb
+-
+README.md
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Palimpsest ChangeLog
+
+## 0.0.1
+
+Initial release.
+
+- Populating working environment from git repo or directory.
+- Flexible asset pipeline with sprockets.
+  * `Palimpsest::Assets` class can be used standalone.
+  * Environment automatically compiles assets referenced in source files.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in palimpsest.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,10 @@
+guard :rspec, cli: '--color --format Fuubar' do
+  watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/palimpsest/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/.+_spec\.rb$})
+  watch('spec/spec_helper.rb') { 'spec' }
+end
+
+guard :yard do
+  watch(%r{^lib/(.+)\.rb$})
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Evan Boyd Sosenko
+
+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

@@ -0,0 +1,70 @@
+# Palimpsest
+
+by Evan Boyd Sosenko.
+
+_No web framework, no problem: Palimpsest gives any custom or legacy project a modern workflow and toolset._
+
+Built flexible, simple, and customizable.
+Palimpsest runs on top of any project and acts as a post processor for your code.
+Features a [Sprockets](https://github.com/sstephenson/sprockets) asset pipeline
+and easy integration with [Kit](https://github.com/razor-x/kit).
+
+[![Dependency Status](https://gemnasium.com/razor-x/palimpsest.png)](https://gemnasium.com/razor-x/palimpsest)
+[![Build Status](https://travis-ci.org/razor-x/palimpsest.png?branch=master)](https://travis-ci.org/razor-x/palimpsest)
+[![Coverage Status](https://coveralls.io/repos/razor-x/palimpsest/badge.png)](https://coveralls.io/r/razor-x/palimpsest)
+[![Code Climate](https://codeclimate.com/github/razor-x/palimpsest.png)](https://codeclimate.com/github/razor-x/palimpsest)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'palimpsest'
+
+And then execute:
+
+````bash
+$ bundle
+````
+
+Or install it yourself as:
+
+````bash
+$ gem install palimpsest
+````
+
+## Usage
+
+**Palimpsest should not be considered stable until version 0.1.0 is released.**
+
+### Documentation
+
+_Comprehensive documentation and examples will be added to this REAME soon._
+
+_For now, reference the YARD documentation below._
+
+The primary documentation for Palimpsest is this README and the YARD source documentation.
+
+YARD documentation for all gem versions is hosted on the [Palimpsest gem page](https://rubygems.org/gems/palimpsest).
+Documentation for the latest commits is hosted on [the RubyDoc.info project page](http://rubydoc.info/github/razor-x/palimpsest/frames).
+
+## Development
+
+### Source Repository
+
+The [Palimpsest source](https://github.com/razor-x/palimpsest) is hosted at github.
+To clone the project run
+
+````bash
+$ git clone git@github.com:razor-x/palimpsest.git
+````
+
+## License
+
+Palimpsest is licensed under the MIT license.
+
+## Warranty
+
+This software is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantibility and fitness for a particular
+purpose.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/gem_tasks'
+require 'bump/tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new :spec
+
+task default: :spec

data/lib/palimpsest/assets.rb

@@ -0,0 +1,189 @@
+require 'active_support/inflector'
+require 'open3'
+require 'sprockets'
+
+module Palimpsest
+
+  # Flexible asset pipeline using Sprockets.
+  # Paths are loaded into a `Sprockets::Environment` (relative to {#directory} if given).
+  # Asset tags are used in source code and replaced
+  # with generated asset path or compiled source if `inline` is used.
+  #
+  # For example, if type is set to `:javascripts` the following replacements would be made:
+  #
+  #     [% javascript app %] -> app-9413c7f112033f0c6f2a8e8dd313399c18d93878.js
+  #     [% javascript lib/jquery %] -> lib/jquery-e2a8cde3f5b3cdb011e38a673556c7a94729e0d1.js
+  #     [% javascript inline tracking %] -> <compiled source of tracking.js asset>
+  #
+  class Assets
+
+    # Default {#options}.
+    DEFAULT_OPTIONS = {
+      # default path to output all saved assets (relative to directory)
+      output: '',
+
+      # assume assets will be served under this url
+      # e.g. `https://cdn.example.com/`
+      cdn: '',
+
+      # keyword to use in asset tag for inline assets
+      inline: 'inline',
+
+      # if true, also generate a gzipped asset
+      gzip: false,
+
+      # include hash in asset name
+      hash: true,
+
+      # opening and closing brackets for asset source tags
+      src_pre: '[%',
+      src_post: '%]',
+
+      # allowed options for `Sprockets::Environment`
+      sprockets_options: [ :js_compressor, :css_compressor ]
+    }
+
+    # @!attribute directory
+    #   @return [String] directory which all paths will be relative to if set
+    #
+    # @!attribute paths
+    #   @return [Array] paths to load into sprockets environment
+    #
+    # @!attribute type
+    #   @return [Symbol] type of asset
+    attr_accessor :directory, :paths, :type
+
+    def initialize directory: '', options: {}, paths: {}
+      self.options options
+      self.directory = directory
+      self.paths = paths
+    end
+
+    # Uses {DEFAULT_OPTIONS} as initial value.
+    # @param options [Hash] merged with current options
+    # @return [Hash] current options
+    def options options={}
+      @options ||= DEFAULT_OPTIONS
+      @options = @options.merge options
+    end
+
+    # @return [Sprockets::Environment] the current sprockets environment
+    def sprockets
+      @sprockets ||= Sprockets::Environment.new
+    end
+
+    # Load options into the sprockets environment.
+    # Values are loaded from {#options}.
+    def load_options
+      options[:sprockets_options].each do |opt|
+        sprockets.send "#{opt}=".to_sym, options[opt] if options[opt]
+      end
+      return self
+    end
+
+    # Load paths into the sprockets environment.
+    # Values are loaded from {#paths}.
+    def load_paths
+      paths.each do |path|
+        sprockets.append_path "#{directory + '/' unless directory.empty?}#{path}"
+      end
+      return self
+    end
+
+    # @return [Sprockets::Environment] sprockets environment with {#options} and {#paths} loaded
+    def assets
+      unless @loaded
+        load_options
+        load_paths
+      end
+      @loaded = true
+      sprockets
+    end
+
+    # Write a target asset to file with a hashed name.
+    # @param target [String] logical path to asset
+    # @param gzip [Boolean] if the asset should be gzipped
+    # @param hash [Boolean] if the asset name should include the hash
+    # @return [String, nil] the relative path to the written asset or `nil` if no such asset
+    def write target, gzip: options[:gzip], hash: options[:hash]
+      asset = assets[target]
+
+      return if asset.nil?
+
+      name = hash ? asset.digest_path : asset.logical_path.to_s
+      name = "#{options[:output]}/#{name}" unless options[:output].empty?
+
+      path = directory.empty? ? '' : "#{directory}/"
+      path << name
+
+      asset.write_to "#{path}.gz", compress: true if gzip
+      asset.write_to path
+      name
+    end
+
+    # (see #update_source)
+    # @note this modifies the `source` `String` in place
+    def update_source! source
+      # e.g. /\[%\s+javascript\s+((\S+)\s?(\S+))\s+%\]/
+      regex = /#{Regexp.escape options[:src_pre]}\s+#{type.to_s.singularize}\s+((\S+)\s?(\S+))\s+#{Regexp.escape options[:src_post]}/
+      source.gsub! regex do
+        if $2 == options[:inline]
+          assets[$3].to_s
+        else
+          asset = write $1
+
+          # @todo raise warning or error if asset not found
+          p "asset not found: #{$1}" and next if asset.nil?
+
+          options[:cdn].empty? ? asset : options[:cdn] + asset
+        end
+      end
+      return true
+    end
+
+    # Replaces all asset tags in source string with asset path or asset source.
+    # Writes any referenced assets to disk.
+    # @param source [String] code to find and replace asset tags
+    # @return [String] copy of `source` with asset tags replaced
+    def update_source source
+      s = source
+      update_source! s
+      s
+    end
+
+    # Scans all non-binary files under `path` ({#directory} by default) for asset tags.
+    # Uses current asset {#type} (if set) and {#options}.
+    # @param path [String] where to look for source files
+    # @return [Array] files with asset tags
+    def find_tags path: directory
+      self.class.find_tags path, type, options
+    end
+
+    # Scans all non-binary files under `path` for asset tags.
+    # @param path [String] where to look for source files
+    # @param type [String, nil] only look for asset tags with this type (or any type if `nil`)
+    # @param options [Hash] merged with {DEFAULT_OPTIONS}
+    # (see #find_tags)
+    def self.find_tags path, type=nil, options={}
+      raise ArgumentError, 'path cannot be empty' if path.empty?
+
+      options = DEFAULT_OPTIONS.merge options
+      pre = Regexp.escape options[:src_pre]
+      post= Regexp.escape options[:src_post]
+
+      cmd = [ 'grep' ]
+      cmd.concat [ '-l', '-I', '-r', '-E' ]
+      cmd << \
+        if type.nil?
+          pre + '(.*?)' + post
+        else
+          pre + '\s+' + type.to_s + '\s+(.*?)' + post
+        end
+      cmd << path
+
+      files = []
+      Open3.capture2(*cmd).first.each_line { |l| files << l.chomp unless l.empty? }
+      files
+    end
+  end
+end

data/lib/palimpsest/environment.rb

@@ -0,0 +1,263 @@
+require 'grit'
+
+module Palimpsest
+
+  # An environment is populated with the contents of
+  # a site's repository at a specified commit.
+  # The environment's files are rooted in a temporary {#directory}.
+  # An environment is the primary way to interact with a site's files.
+  #
+  # An environment loads a {#config} file from the working {#directory};
+  # by default, `palimpsest_config.yml`.
+  #
+  # Paths are all relative to the working {#directory}.
+  #
+  # ````yml
+  # palimpsest_config.yml
+  #
+  # # asset settings
+  # :assets:
+  #   # all options are passed to `Palimpsest::Assets#options` and will use those defaults if unset
+  #   # unless otherwise mentioned, options can be set or overridden per asset type
+  #   :options:
+  #     # opening and closing brackets for asset source tags
+  #     # global option only: cannot be overridden per asset type
+  #     :src_pre: "[%"
+  #     :src_post: "%]"
+  #
+  #     # relative directory to save compiled assets
+  #     :output: compiled
+  #
+  #     # assume assets will be served under here
+  #     :cdn: https://cdn.example.com/
+  #
+  #     # compiled asset names include a uniqe hash by default
+  #     # this can be toggled off
+  #     :hash: false
+  #
+  #   # directories to scan for files with asset tags
+  #   :sources:
+  #     # putting assets/stylesheets first would allow asset tags,
+  #     # e.g. for images, to be used in your stylesheets
+  #     - assets/stylesheets
+  #     - public
+  #     - app/src
+  #
+  #   # all other keys are asset types
+  #   :javascripts:
+  #     :options:
+  #       :js_compressor: :uglifier
+  #     # these paths are loaded into the sprockets environment
+  #     :paths:
+  #       - assets/javascripts
+  #       - other/javascripts
+  #
+  #   # this is another asset type which will have it's own namespace
+  #   :stylesheets:
+  #     :options:
+  #       :css_compressor: :sass
+  #
+  #     :paths:
+  #       - assets/stylesheets
+  #   # images can be part of the asset pipeline
+  #   :images:
+  #     # options can be overridden per type
+  #     :options:
+  #       :output: images
+  #     :paths:
+  #       - assets/images
+  # ````
+  class Environment
+
+    # Default {#options}.
+    DEFAULT_OPTIONS = {
+      # all environment's temporary directories will be rooted under here
+      tmp_dir: '/tmp',
+
+      # prepended to the name of the environment's working directory
+      dir_prefix: 'palimpsest_',
+
+      # name of config file to load, relative to environment's working directory
+      config_file: 'palimpsest_config.yml'
+    }
+
+    # @!attribute site
+    #   @return site to build the environment with
+    #
+    # @!attribute treeish
+    #   @return [String] the reference used to pick the commit to build the environment with
+    #
+    # @!attribute [r] directory
+    #   @return [String] the environment's working directory
+    #
+    # @!attribute [r] populated
+    #   @return [Boolean] true if the site's repo has been extracted
+    attr_reader :site, :treeish, :directory, :populated
+
+    def initialize site: nil, treeish: 'master', options: {}
+      @populated = false
+      self.options options
+      self.site = site if site
+      self.treeish = treeish
+    end
+
+    # Uses {DEFAULT_OPTIONS} as initial value.
+    # @param options [Hash] merged with current options
+    # @return [Hash] current options
+    def options options={}
+      @options ||= DEFAULT_OPTIONS
+      @options = @options.merge options
+    end
+
+    def site= site
+      raise RuntimeError, "Cannot redefine 'site' once populated" if populated
+      @site = site
+    end
+
+    def treeish= treeish
+      raise RuntimeError, "Cannot redefine 'treeish' once populated" if populated
+      raise TypeError unless treeish.is_a? String
+      @treeish = treeish
+    end
+
+    def directory
+      raise RuntimeError if site.nil?
+      if @directory.nil?
+        @directory = Palimpsest::Utility.make_random_directory options[:tmp_dir], "#{options[:dir_prefix]}#{site.name}_"
+      else
+        @directory
+      end
+    end
+
+    # Removes the environment's working directory.
+    def cleanup
+      FileUtils.remove_entry_secure directory if @directory
+      @directory = nil
+      @populated = false
+      return self
+    end
+
+    # Extracts the site's files from repository to the working directory.
+    def populate from: :repo
+      cleanup if populated
+      raise RuntimeError, "Cannot populate without 'site'" if site.nil?
+
+      case from
+      when :repo
+        raise RuntimeError, "Cannot populate without 'treeish'" if treeish.empty?
+        Palimpsest::Utility.extract_repo site.repo, treeish, directory
+      when :source
+        FileUtils.cp_r Dir["#{site.source}/*"], directory
+      end
+
+      @populated = true
+      return self
+    end
+
+    # @return [Hash] configuration loaded from {#options}`[:config_file]` under {#directory}
+    def config
+      populate unless populated
+      @config = YAML.load_file "#{directory}/#{options[:config_file]}"
+      validate_config if @config
+    end
+
+    # @return [Array<Palimpsest::Assets>] assets with settings and paths loaded from config
+    def assets
+      @assets = []
+
+      config[:assets].each do |type, opt|
+        next if [ :sources ].include? type
+        next if opt[:paths].nil?
+
+        assets = Palimpsest::Assets.new directory: directory, paths: opt[:paths]
+        assets.options config[:assets][:options] unless config[:assets][:options].nil?
+        assets.options opt[:options] unless opt[:options].nil?
+        assets.type = type
+        @assets << assets
+      end unless config[:assets].nil?
+
+      @assets
+    end
+
+    # @return [Array] all source files with asset tags
+    def sources_with_assets
+      return [] if config[:assets].nil?
+      return [] if config[:assets][:sources].nil?
+
+      @sources_with_assets = []
+
+      opts = {}
+      [ :src_pre, :src_post ].each do |opt|
+        opts[opt] = config[:assets][:options][opt] unless config[:assets][:options][opt].nil?
+      end unless config[:assets][:options].nil?
+
+      config[:assets][:sources].each do |path|
+        @sources_with_assets << Palimpsest::Assets.find_tags("#{directory}/#{path}", nil, opts)
+      end
+
+      @sources_with_assets.flatten
+    end
+
+    # Finds all assets in {#sources_with_assets} and
+    # generates the assets and updates the sources.
+    def compile_assets
+      sources_with_assets.each do |file|
+        source = File.read file
+        assets.each { |a| a.update_source! source }
+        Palimpsest::Utility.write source, file
+      end
+      return self
+    end
+
+    private
+
+    # Checks the config file for invalid settings.
+    #
+    # - Checks that paths are not absolute or use `../` or `~/`.
+    def validate_config
+      message = 'bad path in config'
+
+      def safe_path?(path) Palimpsest::Utility.safe_path?(path) end
+
+      # Checks the option in the asset key.
+      def validate_asset_options opts
+        opts.each do |k,v|
+          raise RuntimeError, 'bad option in config' if k == :sprockets_options
+          raise RuntimeError, message if k == :output && ! safe_path?(v)
+        end
+      end
+
+      @config[:assets].each do |k, v|
+
+        # process @config[:assets][:options] then go to the next option
+        if k == :options
+          validate_asset_options v
+          next
+        end unless v.nil?
+
+        # process @config[:assets][:sources] then go to the next option
+        if k == :sources
+          v.each_with_index do |source, i|
+            raise RuntimeError, message unless safe_path? source
+          end
+          next
+        end
+
+        # process each asset type in @config[:assets]
+        v.each do |asset_key, asset_value|
+          # process :options
+          if asset_key == :options
+            validate_asset_options asset_value
+            next
+          end unless asset_value.nil?
+
+          # process each asset path
+          asset_value.each_with_index do |path, i|
+            raise RuntimeError, message unless safe_path? path
+          end
+        end
+      end unless @config[:assets].nil?
+      @config
+    end
+  end
+end