palimpsest 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bb9471fad6a53da1e1cc97a04c7883e81bfa6756
-  data.tar.gz: ad2694a1fecbbe589e1bd2287d003398c0d4408c
+  metadata.gz: 786935525c8fd9d713375ffc0b13e52bae005eb7
+  data.tar.gz: 9b1f0e46de8b8d23fd44a55034e1ce87529c135a
 SHA512:
-  metadata.gz: 44c0455bd09f9084fbb2b90cd24c97f833ccb2e70594788a0632846955db6a8dd23b43425ac4e68a740a1c0c0a5c9b8c5c05e91bc831c50a4fdaf6cc413aa2fd
-  data.tar.gz: 6e9e38fa4cead06576012f74eda7cc94baf115578be4fd282a810ae7586d13dcbe19a0ccdc595e76cd4bf7ea51bd520a156023f6ad69228eb09a7264fd759431
+  metadata.gz: 7a405c655b0aa0024da55885d687e89cabe671705ba2dde83c1875ee911b04c297856dc97cf05ea85f79544ae35f49c6f8a7cb354993bb356d61c61e65e757ca
+  data.tar.gz: c139bd33702b70b8297f6f5eab2d0a1289f74249e95fd8fd68c184f1c1e7b5b8349f614ac3b7db538d836971c41c74597ced18ac2f98cdce2911058a382b31bd

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Palimpsest ChangeLog
 
+## 0.1.0
+
+- Lots of documentation and improvements.
+- New classes: Site, Component, External.
+- Environment support for new classes.
+
 ## 0.0.1
 
 Initial release.

data/README.md

@@ -9,16 +9,20 @@ 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).
 
+[![Gem Version](https://badge.fury.io/rb/palimpsest.png)](http://badge.fury.io/rb/palimpsest)
 [![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)
+[![githalytics.com alpha](https://cruel-carlota.pagodabox.com/428992451dfb452dbd522644cbb17f71 "githalytics.com")](http://githalytics.com/razor-x/palimpsest)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'palimpsest'
+````ruby
+gem 'palimpsest'
+````
 
 And then execute:
 
@@ -32,20 +36,131 @@ Or install it yourself as:
 $ gem install palimpsest
 ````
 
+## Documentation
+
+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).
+
 ## Usage
 
-**Palimpsest should not be considered stable until version 0.1.0 is released.**
+**Palimpsest should not be considered stable until version 1.0.0 is released.**
 
-### Documentation
+This README will focus on examples of how to get your project working with Palimpsest through `Palimpsest::Environment`.
 
-_Comprehensive documentation and examples will be added to this REAME soon._
+Palimpsest's classes are independently useful outside of `Palimpsest::Environment`, and each is
+[well documented for that purpose](http://rubydoc.info/github/razor-x/palimpsest/frames).
 
-_For now, reference the YARD documentation below._
+The first step is always
 
-The primary documentation for Palimpsest is this README and the YARD source documentation.
+````ruby
+require 'palimpsest'
+````
+### Additional requirements
 
-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).
+Some optional Palimpsest features depend on gems not required by Palimpsest itself.
+Include these in your project's Gemfile if you plan to use them.
+
+For example, to use the `image_compression` option, add to your Gemfile
+
+````ruby
+gem 'sprockets-image_compressor'
+````
+
+and to your project
+
+````ruby
+require 'sprockets-image_compressor'
+````
+
+or if you set `js_compressor: uglifier` you must add to your Gemfile
+
+````ruby
+gem 'uglifier'
+````
+
+and to your project
+
+````ruby
+require 'uglifier'
+````
+
+Similarly you must include gems for any sprockets engines you want to use.
+
+### Creating and populating an environment
+
+Create an environment with
+
+````ruby
+environment = Palimpsest::Environment.new
+````
+For most operations you will need to specify a `site` which can be any object which
+responds to the methods `Palimpsest::Environment` assumes exists in some of its own methods.
+A model class `Palimpsest::Site` is included which implements all possible expected methods.
+Finally, the examples below assume default options for each class, but these can be overridden with `#options`.
+
+````ruby
+site = Palimpsest::Site.new
+site.name = 'my_app'
+environment.site = site
+````
+
+To populate the environment from a git repo,
+
+````ruby
+site.repo = Grit::Repo.new '/path/to/project/repo'
+environment.treeish = 'my_feature' # if you want something other then 'master'
+environment.populate
+````
+or to populate from a directory,
+
+````ruby
+site.source = '/path/to/project/source'
+environment.populate from :source
+````
+Either way you will get a copy of your site in a new random working directory,
+
+````ruby
+environment.directory #=> '/tmp/palimpsest_my_app_6025680'
+````
+
+### Working with the environment
+
+If you project contains a file `palimpsest_config.yml`,
+then its configuration is available with `environment.config`.
+
+[**An example `palimpsest_config.yml`.**](http://rubydoc.info/github/razor-x/palimpsest/Palimpsest/Environment)
+
+The configuration file tells Palimpsest how to behave when you ask it to manipulate the environment
+and acts as a shortcut to working with the other Palimpsest classes directly.
+
+If you made it this far, you can make Palimpsest do all sorts of magic to your code in the working directory.
+
+For example, to search through you code for tags referencing assets,
+process and save those assets with sprockets,
+and replace the tags with references to the processed assets,
+
+````ruby
+environment.compile_assets
+````
+Check the [`Palimpsest::Environment` documentation](http://rubydoc.info/github/razor-x/palimpsest/Palimpsest/Environment)
+for all available magic, and freely extend the class to add new magic applicable to your project.
+
+### Finishing with the environment
+
+You can copy the current state of the environment to another directory with `Palimpsest::Environment#copy`.
+By default, this will use `site.path` for the destination, or you can specify with
+
+````ruby
+environment.copy dest: '/path/to/out/dir'
+````
+
+To delete the working directory, use
+
+````ruby
+environment.cleanup
+````
 
 ## Development
 

data/lib/palimpsest/assets.rb

@@ -29,6 +29,9 @@ module Palimpsest
       # keyword to use in asset tag for inline assets
       inline: 'inline',
 
+      # if true, use sprockets-image_compressor with pngcrush and jpegoptim
+      image_compression: false,
+
       # if true, also generate a gzipped asset
       gzip: false,
 
@@ -40,7 +43,7 @@ module Palimpsest
       src_post: '%]',
 
       # allowed options for `Sprockets::Environment`
-      sprockets_options: [ :js_compressor, :css_compressor ]
+      sprockets_options: [:js_compressor, :css_compressor]
     }
 
     # @!attribute directory
@@ -78,7 +81,12 @@ module Palimpsest
       options[:sprockets_options].each do |opt|
         sprockets.send "#{opt}=".to_sym, options[opt] if options[opt]
       end
-      return self
+
+      if options[:image_compression]
+        Sprockets::ImageCompressor::Integration.setup sprockets
+      end
+
+      self
     end
 
     # Load paths into the sprockets environment.
@@ -87,7 +95,7 @@ module Palimpsest
       paths.each do |path|
         sprockets.append_path "#{directory + '/' unless directory.empty?}#{path}"
       end
-      return self
+      self
     end
 
     # @return [Sprockets::Environment] sprockets environment with {#options} and {#paths} loaded
@@ -165,15 +173,15 @@ module Palimpsest
     # @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?
+      fail 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 << \
+      cmd = ['grep']
+      cmd.concat %w(-l -I -r -E)
+      cmd <<
         if type.nil?
           pre + '(.*?)' + post
         else

data/lib/palimpsest/component.rb

@@ -0,0 +1,33 @@
+module Palimpsest
+
+  # Use this class to store parts of your project in a location
+  # separate from the normal installed location.
+  #
+  # For example, put custom templates in `components/my_app/templates`
+  # which might later be installed to `apps/my_app/templates`.
+  #
+  # This is useful when `apps/my_app` is a separate project
+  # with its own repository loaded using {Palimpsest::External}.
+  class Component
+
+    # @!attribute source_path
+    #   @return [String] source path for component
+    #
+    # @!attribute install_path
+    #   @return [String] install path for component
+    attr_accessor :source_path, :install_path
+
+    def initialize source_path: '', install_path: ''
+      self.source_path = source_path
+      self.install_path = install_path
+    end
+
+    # Installs files in {#source_path} to {#install_path}
+    def install
+      fail RuntimeError if source_path.empty?
+      fail RuntimeError if install_path.empty?
+      FileUtils.mkdir_p install_path
+      FileUtils.mv Dir["#{source_path}/*"], install_path
+    end
+  end
+end

data/lib/palimpsest/environment.rb

@@ -1,9 +1,8 @@
-require 'grit'
-
 module Palimpsest
 
   # An environment is populated with the contents of
   # a site's repository at a specified commit.
+  # Alternatively, a single directory can be used to populate the environment.
   # The environment's files are rooted in a temporary {#directory}.
   # An environment is the primary way to interact with a site's files.
   #
@@ -13,11 +12,33 @@ module Palimpsest
   # Paths are all relative to the working {#directory}.
   #
   # ````yml
-  # palimpsest_config.yml
+  # # example of palimpsest_config.yml
+  #
+  # # component settings
+  # :components:
+  #   # all component paths are relative to the base
+  #   :base: _components
+  #
+  #   # list of components
+  #   :paths:
+  #    #- [ components_path, install_path ]
+  #     - [ my_app/templates, apps/my_app/templates ]
+  #     - [ my_app/extra, apps/my_app ]
   #
+  # # externals settings
+  # :externals:
+  #   # server or local path that repos are under
+  #   :server: "https://github.com/razor-x"
+  #
+  #   # list of external repos
+  #   :repos:
+  #   #- [ name, install_path, branch, server (optional) ]
+  #    - [ my_app, apps/my_app, master ]
+  #    - [ sub_app, apps/my_app/sub_app, my_feature, "https://bitbucket.org/razorx" ]
   # # asset settings
   # :assets:
-  #   # all options are passed to `Palimpsest::Assets#options` and will use those defaults if unset
+  #   # all options are passed to Assets#options
+  #   # options will use defaults set in Palimpsest::Asset::DEFAULT_OPTIONS if unset here
   #   # unless otherwise mentioned, options can be set or overridden per asset type
   #   :options:
   #     # opening and closing brackets for asset source tags
@@ -61,8 +82,10 @@ module Palimpsest
   #       - assets/stylesheets
   #   # images can be part of the asset pipeline
   #   :images:
-  #     # options can be overridden per type
   #     :options:
+  #       # requires the sprockets-image_compressor gem
+  #       :image_compression: true
+  #        # options can be overridden per type
   #       :output: images
   #     :paths:
   #       - assets/images
@@ -87,12 +110,9 @@ module Palimpsest
     # @!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
+    attr_reader :site, :treeish, :populated
 
     def initialize site: nil, treeish: 'master', options: {}
       @populated = false
@@ -109,49 +129,71 @@ module Palimpsest
       @options = @options.merge options
     end
 
+    # @see Environment#site
     def site= site
-      raise RuntimeError, "Cannot redefine 'site' once populated" if populated
+      fail RuntimeError, "Cannot redefine 'site' once populated" if populated
       @site = site
     end
 
+    # @see Environment#treeish
     def treeish= treeish
-      raise RuntimeError, "Cannot redefine 'treeish' once populated" if populated
-      raise TypeError unless treeish.is_a? String
+      fail RuntimeError, "Cannot redefine 'treeish' once populated" if populated
+      fail TypeError unless treeish.is_a? String
       @treeish = treeish
     end
 
+    # @return [String] the environment's working directory
     def directory
-      raise RuntimeError if site.nil?
       if @directory.nil?
-        @directory = Palimpsest::Utility.make_random_directory options[:tmp_dir], "#{options[:dir_prefix]}#{site.name}_"
+        name = site.nil? ? '' : site.name
+        @directory = Utility.make_random_directory options[:tmp_dir], "#{options[:dir_prefix]}#{name}_"
       else
         @directory
       end
     end
 
+    # Copy the contents of the working directory.
+    # @param dest [String] path to copy environment's files to
+    # @return [Environment] the current environment instance
+    def copy dest: site.path
+      FileUtils.cp_r Dir["#{directory}/*"], dest, preserve: true
+      self
+    end
+
     # Removes the environment's working directory.
+    # @return [Environment] the current environment instance
     def cleanup
       FileUtils.remove_entry_secure directory if @directory
       @directory = nil
+      @assets = []
+      @components = []
       @populated = false
-      return self
+      self
     end
 
     # Extracts the site's files from repository to the working directory.
-    def populate from: :repo
+    # @return [Environment] the current environment instance
+    def populate from: :auto
       cleanup if populated
-      raise RuntimeError, "Cannot populate without 'site'" if site.nil?
+      fail RuntimeError, "Cannot populate without 'site'" if site.nil?
 
       case from
+      when :auto
+        if site.respond_to?(:repo) ? site.repo : nil
+          populate from: :repo
+        else
+          populate from: :source
+        end
       when :repo
-        raise RuntimeError, "Cannot populate without 'treeish'" if treeish.empty?
-        Palimpsest::Utility.extract_repo site.repo, treeish, directory
+        fail RuntimeError, "Cannot populate without 'treeish'" if treeish.empty?
+        Utility.extract_repo site.repo, treeish, directory
+        @populated = true
       when :source
-        FileUtils.cp_r Dir["#{site.source}/*"], directory
+        FileUtils.cp_r Dir["#{site.source}/*"], directory, preserve: true
+        @populated = true
       end
 
-      @populated = true
-      return self
+      self
     end
 
     # @return [Hash] configuration loaded from {#options}`[:config_file]` under {#directory}
@@ -161,15 +203,65 @@ module Palimpsest
       validate_config if @config
     end
 
-    # @return [Array<Palimpsest::Assets>] assets with settings and paths loaded from config
+    # @return [Array<Component>] components with paths loaded from config
+    def components
+      return @components if @components
+      return [] if config[:components].nil?
+      return [] if config[:components][:paths].nil?
+
+      @components = []
+
+      base = directory
+      base += config[:components][:base].nil? ? '' : '/' + config[:components][:base]
+
+      config[:components][:paths].each do |paths|
+       @components << Component.new(source_path: "#{base}/#{paths[0]}", install_path: "#{directory}/#{paths[1]}")
+      end
+
+      @components
+    end
+
+    # Install all components.
+    # @return [Environment] the current environment instance
+    def install_components
+      components.each { |c| c.install }
+      self
+    end
+
+    # @return [Array<External>] externals loaded from config
+    def externals
+      return @externals if @externals
+      return [] if config[:externals].nil?
+      return [] if config[:externals][:repos].nil?
+
+      @externals = []
+
+      config[:externals][:repos].each do |repo|
+        source = repo[3].nil? ? config[:externals][:server] : repo[3]
+        @externals << External.new(name: repo[0], source: source, branch: repo[2], install_path: "#{directory}/#{repo[1]}" )
+      end
+
+      @externals
+    end
+
+    # Install all externals.
+    # @return [Environment] the current environment instance
+    def install_externals
+      externals.each { |e| e.install }
+      self
+    end
+
+    # @return [Array<Assets>] assets with settings and paths loaded from config
     def assets
+      return @assets if @assets
+
       @assets = []
 
       config[:assets].each do |type, opt|
-        next if [ :sources ].include? type
+        next if [:sources].include? type
         next if opt[:paths].nil?
 
-        assets = Palimpsest::Assets.new directory: directory, paths: opt[:paths]
+        assets = 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
@@ -187,12 +279,12 @@ module Palimpsest
       @sources_with_assets = []
 
       opts = {}
-      [ :src_pre, :src_post ].each do |opt|
+      [: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)
+        @sources_with_assets << Assets.find_tags("#{directory}/#{path}", nil, opts)
       end
 
       @sources_with_assets.flatten
@@ -200,35 +292,57 @@ module Palimpsest
 
     # Finds all assets in {#sources_with_assets} and
     # generates the assets and updates the sources.
+    # @return [Environment] the current environment instance
     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
+        Utility.write source, file, preserve: true
       end
-      return self
+      self
     end
 
     private
 
     # Checks the config file for invalid settings.
-    #
+    # @todo refactor this
     # - 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)
+          fail RuntimeError, 'bad option in config' if k == :sprockets_options
+          fail RuntimeError, message if k == :output && ! Utility.safe_path?(v)
         end
       end
 
-      @config[:assets].each do |k, v|
+      @config[:external].each do |k, v|
+        next if k == :server
 
+        v.each do |repo|
+          fail RuntimeError, message unless Utility.safe_path? repo[1]
+        end unless v.nil?
+      end unless @config[:external].nil?
+
+      @config[:components].each do |k,v|
+        # process @config[:components][:base] then go to the next option
+        if k == :base
+          fail RuntimeError, message unless Utility.safe_path? v
+          next
+        end unless v.nil?
+
+        # process @config[:components][:paths]
+        if k == :paths
+          v.each do |path|
+            fail RuntimeError, message unless Utility.safe_path? path[0]
+            fail RuntimeError, message unless Utility.safe_path? path[1]
+          end
+        end
+      end unless @config[:components].nil?
+
+      @config[:assets].each do |k, v|
         # process @config[:assets][:options] then go to the next option
         if k == :options
           validate_asset_options v
@@ -238,7 +352,7 @@ module Palimpsest
         # 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
+            fail RuntimeError, message unless Utility.safe_path? source
           end
           next
         end
@@ -253,10 +367,11 @@ module Palimpsest
 
           # process each asset path
           asset_value.each_with_index do |path, i|
-            raise RuntimeError, message unless safe_path? path
+            fail RuntimeError, message unless Utility.safe_path? path
           end
         end
       end unless @config[:assets].nil?
+
       @config
     end
   end

data/lib/palimpsest/external.rb

@@ -0,0 +1,74 @@
+module Palimpsest
+
+  # Use this class to manage external repositories you want to include in your project.
+  #
+  # Given a name, source and branch, the contents of the repository at the HEAD of the branch
+  # will be available as an {Environment} object through {#environment}.
+  #
+  # Use {#cleanup} to remove all files created by the {#External} object.
+  class External
+
+    # @!attribute name
+    #   @return [String] repository name
+    #
+    # @!attribute source
+    #   @return [String] base source url or path to external git repo (without name)
+    #
+    # @!attribute branch
+    #   @return [String] branch to use for treeish
+    #
+    # @!attribute install_path
+    #   @return [String] where the files will be installed to
+    attr_accessor :name, :source, :branch, :install_path
+
+    def initialize name: '', source: '', branch: 'master', install_path: ''
+      self.name = name
+      self.source = source
+      self.branch = branch
+      self.install_path = install_path
+    end
+
+    def repo_path
+      ( source.empty? || name.empty? ) ? '' : "#{source}/#{name}"
+    end
+
+    # @return [Environment] environment with contents of the repository at the HEAD of the branch
+    def environment
+      return @environment if @environment
+
+      site = Site.new repo: Grit::Repo.new(tmp_environment.directory)
+      @environment = Environment.new site: site, treeish: branch
+    end
+
+    # Copy the files to the {#install_path}.
+    # @return (see Environment#copy)
+    def install
+      environment.copy dest: install_path
+    end
+
+    # @return [External] the current external instance
+    def cleanup
+      environment.cleanup if @environment
+      @environment = nil
+
+      tmp_environment.cleanup if @tmp_environment
+      @tmp_environment = nil
+      self
+    end
+
+    # @return [Environment] temporary environment to hold the cloned repository
+    def tmp_environment
+      return @tmp_environment if @tmp_environment
+
+      fail RuntimeError if repo_path.empty?
+
+      Grit::Git.git_max_size = 200 * 1048576
+      Grit::Git.git_timeout = 200
+
+      @tmp_environment = Environment.new
+      gritty = Grit::Git.new tmp_environment.directory
+      gritty.clone( { branch: branch }, repo_path, tmp_environment.directory )
+      @tmp_environment
+    end
+  end
+end

data/lib/palimpsest/site.rb

@@ -0,0 +1,23 @@
+module Palimpsest
+
+  # Model site object used by {Environment#site}.
+  class Site
+
+    # @!attribute name
+    #   @return [String] name for this site
+    #
+    # @!attribute repo
+    #   @return [Grit::Repo] grit repo for this site
+    #
+    # @!attribute source
+    #   @return [String] path to source code for this site
+    attr_accessor :name, :repo, :source, :path
+
+    def initialize name: '', repo: nil, source: ''
+      self.name = name
+      self.repo = repo
+      self.source = source
+      self.path = path
+    end
+  end
+end

data/lib/palimpsest/utility.rb

@@ -38,8 +38,8 @@ module Palimpsest
     # @return [String] input path if valid
     def self.validate_path path, root=''
       case
-      when path[/(\.\.\/|~\/)/] then raise RuntimeError
-      when File.expand_path(path, root)[/^#{root}/].nil? then raise RuntimeError
+      when path[/(\.\.\/|~\/)/] then fail RuntimeError
+      when File.expand_path(path, root)[/^#{root}/].nil? then fail RuntimeError
       else path
       end
     end
@@ -48,22 +48,18 @@ module Palimpsest
     # @param [Grit::Repo] repo
     # @param [String] treeish
     # @param [String] directory
-    def self.extract_repo repo, treeish, directory, files: nil
+    def self.extract_repo repo, treeish, directory
       input = Archive::Tar::Minitar::Input.new StringIO.new(repo.archive_tar treeish)
-      input.each do |entry|
-        if files.nil?
-          input.extract_entry directory, entry
-        else
-          input.extract_entry directory, entry if files.include? entry.name
-        end
-      end
+      input.each { |e| input.extract_entry directory, e }
     end
 
     # Write contents to file.
     # @param contents [String]
     # @param file [String]
-    def self.write contents, file
+    def self.write contents, file, preserve: false
+      original_time = File.mtime file if preserve
       File.open(file, 'w') { |f| f.write contents }
+      File.utime original_time, original_time, file if preserve
     end
   end
 end

data/lib/palimpsest/version.rb

@@ -1,4 +1,4 @@
 module Palimpsest
   # Palimpsest version.
-  VERSION = '0.0.1'
+  VERSION = '0.1.0'
 end

data/lib/palimpsest.rb

@@ -1,7 +1,12 @@
+require 'grit'
+
 require 'palimpsest/version'
+require 'palimpsest/utility'
+require 'palimpsest/site'
 require 'palimpsest/assets'
+require 'palimpsest/component'
+require 'palimpsest/external'
 require 'palimpsest/environment'
-require 'palimpsest/utility'
 
 # No web framework, no problem:
 # Palimpsest gives any custom or legacy project # a modern workflow and toolset.

data/spec/component_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+
+describe Palimpsest::Component do
+
+  subject(:component) { Palimpsest::Component.new }
+
+  describe "#install" do
+
+    it "fails if no source path" do
+      component.install_path = 'install/path'
+      expect { component.install }.to raise_error RuntimeError
+    end
+
+    it "fails if no install path" do
+      component.source_path = 'src/path'
+      expect { component.install }.to raise_error RuntimeError
+    end
+
+    it "moves the component to the install path" do
+      component.source_path = 'src/path'
+      component.install_path = 'install/path'
+      allow(Dir).to receive(:[]).with('src/path/*').and_return( %w(src/path/1 src/path/2) )
+      expect(FileUtils).to receive(:mkdir_p).with('install/path')
+      expect(FileUtils).to receive(:mv).with(%w(src/path/1 src/path/2), 'install/path')
+      component.install
+    end
+  end
+end

data/spec/environment_spec.rb

@@ -2,17 +2,11 @@ require 'spec_helper'
 
 describe Palimpsest::Environment do
 
-  let(:site_1) { double name: 'site_1' }
-  let(:site_2) { double name: 'site_2' }
+  let(:site_1) { Palimpsest::Site.new name: 'site_1' }
+  let(:site_2) { Palimpsest::Site.new name: 'site_2' }
 
   subject(:environment) { Palimpsest::Environment.new }
 
-  after :all do
-    Dir.glob("#{Palimpsest::Environment.new.options[:tmp_dir]}/#{Palimpsest::Environment.new.options[:dir_prefix]}*").each do |dir|
-      FileUtils.remove_entry_secure dir
-    end
-  end
-
   describe ".new" do
 
     it "sets default options" do
@@ -63,36 +57,33 @@ describe Palimpsest::Environment do
 
   describe "#directory" do
 
-    context "when required values set" do
-
-      subject(:environment) { Palimpsest::Environment.new site: site_1 }
-
-      before :each do
-        allow(Palimpsest::Utility).to receive(:make_random_directory).and_return('/tmp/rand_dir')
-      end
+    before :each do
+      allow(Palimpsest::Utility).to receive(:make_random_directory).and_return('/tmp/rand_dir')
+    end
 
-      context "when directory is unset" do
+    context "when directory is unset" do
 
-        it "makes and returns a random directory" do
-          expect(environment.directory).to eq '/tmp/rand_dir'
-        end
+      it "makes and returns a random directory" do
+        expect(environment.directory).to eq '/tmp/rand_dir'
       end
+    end
 
-      context "when directory is set" do
+    context "when directory is set" do
 
-        it "returns the current directory" do
-          expect(Palimpsest::Utility).to receive(:make_random_directory).once
-          environment.directory
-          expect(environment.directory).to eq '/tmp/rand_dir'
-        end
+      it "returns the current directory" do
+        expect(Palimpsest::Utility).to receive(:make_random_directory).once
+        environment.directory
+        expect(environment.directory).to eq '/tmp/rand_dir'
       end
     end
+  end
 
-    context "when required values are not set" do
-
-      it "fails if site is not set" do
-        expect { environment.directory }.to raise_error RuntimeError
-      end
+  describe "#copy" do
+    it "moves the component to the install path" do
+      dir = environment.directory
+      allow(Dir).to receive(:[]).with("#{dir}/*").and_return( %W(#{dir}/path/1 #{dir}/path/2) )
+      expect(FileUtils).to receive(:cp_r).with( %W(#{dir}/path/1 #{dir}/path/2), '/dest/path', preserve: true)
+      environment.copy dest: '/dest/path'
     end
   end
 
@@ -106,6 +97,10 @@ describe Palimpsest::Environment do
       environment.cleanup
       expect(environment.instance_variable_get :@directory).to eq nil
     end
+
+    it "returns itself" do
+      expect(environment.cleanup).to be environment
+    end
   end
 
   describe "#populate" do
@@ -120,40 +115,40 @@ describe Palimpsest::Environment do
       subject(:environment) { Palimpsest::Environment.new site: site_1, treeish: 'master' }
 
       before :each do
-        allow(site_1).to receive(:repo).and_return(double Grit::Repo)
+        site_1.repo = double Grit::Repo
         allow(Palimpsest::Utility).to receive :extract_repo
       end
 
       it "extracts the repo to the directory and sets populated true" do
         expect(Palimpsest::Utility).to receive(:extract_repo).with(site_1.repo, 'master', environment.directory)
-        environment.populate
+        environment.populate from: :repo
         expect(environment.populated).to eq true
       end
 
       it "fails when missing treeish" do
         environment.site = site_1
         environment.treeish = ''
-        expect { environment.populate }.to raise_error RuntimeError, /populate without/
+        expect { environment.populate from: :repo }.to raise_error RuntimeError, /populate without/
       end
 
       it "returns itself" do
-        expect(environment.populate).to be environment
+        expect(environment.populate from: :repo).to be environment
       end
 
       it "will cleanup if populated" do
         environment.populate
         expect(environment).to receive :cleanup
-        environment.populate
+        environment.populate from: :repo
       end
     end
 
-    context "populate from directory" do
+    context "populate from source" do
 
-      it "copies the source files to the directory" do
+      it "copies the source files to the directory preserving mtime" do
         environment.site = site_1
-        allow(site_1).to receive(:source).and_return('/path/to/source')
+        site_1.source = '/path/to/source'
         allow(Dir).to receive(:[]).with('/path/to/source/*').and_return( %w(dir_1 dir_2) )
-        expect(FileUtils).to receive(:cp_r).with( %w(dir_1 dir_2), environment.directory )
+        expect(FileUtils).to receive(:cp_r).with( %w(dir_1 dir_2), environment.directory, preserve: true )
         environment.populate from: :source
       end
     end
@@ -189,6 +184,16 @@ describe Palimpsest::Environment do
 
     let(:config) do
       YAML.load <<-EOF
+        :components:
+          :base: _components
+          :paths:
+            - [ my_app/templates, apps/my_app/templates ]
+            - [ my_app/extra, apps/my_app ]
+        :externals:
+          :server: "https://github.com/razor-x"
+          :repos:
+            - [ my_app, apps/my_app, master ]
+            - [ sub_app, apps/my_app/sub_app, my_feature, "https://bitbucket.org/razorx" ]
         :assets:
           :options:
             :output: compiled
@@ -219,6 +224,85 @@ describe Palimpsest::Environment do
       allow(environment).to receive(:config).and_return(config)
     end
 
+    describe "#components" do
+
+      it "returns an array" do
+        expect(environment.components).to be_a Array
+      end
+
+     it "contains components" do
+        expect(environment.components[0]).to be_a Palimpsest::Component
+        expect(environment.components[1]).to be_a Palimpsest::Component
+      end
+
+      it "sets the components source and install paths" do
+        expect(environment.components[0].source_path).to eq "#{environment.directory}/_components/my_app/templates"
+        expect(environment.components[0].install_path).to eq "#{environment.directory}/apps/my_app/templates"
+      end
+    end
+
+    describe "#install_components" do
+
+      it "installs the components" do
+        expect(environment.components[0]).to receive(:install)
+        expect(environment.components[1]).to receive(:install)
+        environment.install_components
+      end
+
+      it "returns itself" do
+        expect(environment.install_components).to be environment
+      end
+    end
+
+    describe "#externals" do
+
+      it "returns an array" do
+        expect(environment.externals).to be_a Array
+      end
+
+      it "contains externals" do
+        expect(environment.externals[0]).to be_a Palimpsest::External
+        expect(environment.externals[1]).to be_a Palimpsest::External
+      end
+
+      it "sets the externals repo path" do
+        expect(environment.externals[0].repo_path).to eq 'https://github.com/razor-x/my_app'
+        expect(environment.externals[1].repo_path).to eq 'https://bitbucket.org/razorx/sub_app'
+      end
+
+      it "sets the externals branch" do
+        expect(environment.externals[0].branch).to eq 'master'
+        expect(environment.externals[1].branch).to eq 'my_feature'
+      end
+
+      it "sets the install path" do
+        expect(environment.externals[0].install_path).to eq "#{environment.directory}/apps/my_app"
+        expect(environment.externals[1].install_path).to eq "#{environment.directory}/apps/my_app/sub_app"
+      end
+    end
+
+    describe "#install_externals" do
+
+      let(:external_1) { double Palimpsest::External }
+      let(:external_2) { double Palimpsest::External }
+
+      before :each do
+        allow(environment).to receive(:externals).and_return( [ external_1, external_2 ] )
+        allow(external_1).to receive(:install)
+        allow(external_2).to receive(:install)
+      end
+
+      it "installs the externals" do
+        expect(external_1).to receive(:install)
+        expect(external_2).to receive(:install)
+        environment.install_externals
+      end
+
+      it "returns itself" do
+        expect(environment.install_externals).to be environment
+      end
+    end
+
     describe "#assets" do
 
       subject(:assets) { environment.assets }
@@ -292,12 +376,12 @@ describe Palimpsest::Environment do
         expect(environment.compile_assets).to be environment
       end
 
-      it "compiles the assets and writes the sources" do
+      it "compiles the assets and writes the sources while preserving mtime" do
         allow(environment).to receive(:sources_with_assets).and_return sources
         allow(File).to receive(:read).with(sources[0]).and_return('data_1')
         allow(File).to receive(:read).with(sources[1]).and_return('data_2')
-        expect(Palimpsest::Utility).to receive(:write).with 'data_1', sources[0]
-        expect(Palimpsest::Utility).to receive(:write).with 'data_2', sources[1]
+        expect(Palimpsest::Utility).to receive(:write).with 'data_1', sources[0], preserve: true
+        expect(Palimpsest::Utility).to receive(:write).with 'data_2', sources[1], preserve: true
         environment.compile_assets
       end
     end

data/spec/external_spec.rb

@@ -0,0 +1,86 @@
+require 'spec_helper'
+
+describe Palimpsest::External do
+
+  subject(:external) { Palimpsest::External.new name: 'my_app', source: 'path/to/source', branch: 'my_feature' }
+
+  let(:gritty) { double Grit::Git }
+  let(:repo) { double Grit::Repo }
+
+  before :each do
+    allow(Grit::Git).to receive(:new).and_return(gritty)
+    allow(Grit::Repo).to receive(:new).and_return(repo)
+    allow(gritty).to receive(:clone)
+  end
+
+  describe "#repo_path" do
+
+    it "gives the full path to the source repo" do
+      expect(external.repo_path).to eq 'path/to/source/my_app'
+    end
+  end
+
+  describe "#environment" do
+
+    it "returns a new environment" do
+      expect(external.environment).to be_a Palimpsest::Environment
+    end
+
+    it "sets the treeish for the environment" do
+      expect(external.environment.treeish).to eq 'my_feature'
+    end
+
+    it "sets the repo for the environment" do
+      expect(external.environment.site.repo).to equal repo
+    end
+  end
+
+  describe "#tmp_environment" do
+
+    it "fails if no repo path" do
+      external.name = ''
+      external.source = ''
+      expect { external.tmp_environment }.to raise_error RuntimeError
+    end
+
+    it "returns a new environment" do
+      expect(external.tmp_environment).to be_a Palimpsest::Environment
+    end
+
+    it "sets the treeish for the environment" do
+      expect(gritty).to receive(:clone).with( { branch: 'my_feature' }, external.repo_path, anything )
+      external.tmp_environment
+    end
+  end
+
+  describe "#cleanup" do
+
+    it "cleans environment" do
+      expect(external.environment).to receive(:cleanup)
+      external.cleanup
+    end
+    it "clears @environment" do
+      expect(external.instance_variable_get :@environment).to be_nil
+      external.cleanup
+    end
+
+    it "cleans tmp_environment" do
+      expect(external.tmp_environment).to receive(:cleanup)
+      external.cleanup
+    end
+
+    it "clears @tmp_environment" do
+      expect(external.instance_variable_get :@tmp_environment).to be_nil
+      external.cleanup
+    end
+  end
+
+  describe "#install" do
+
+    it "installs the external to the install path" do
+      external.install_path = 'path/to/install'
+      expect(external.environment).to receive(:copy).with(dest: 'path/to/install')
+      external.install
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -12,4 +12,10 @@ SimpleCov.start
 
 RSpec.configure do |c|
   c.expect_with(:rspec) { |e| e.syntax = :expect }
+
+  c.after :suite do
+    Dir.glob("#{Palimpsest::Environment.new.options[:tmp_dir]}/#{Palimpsest::Environment.new.options[:dir_prefix]}*").each do |dir|
+      FileUtils.remove_entry_secure dir
+    end
+  end
 end

data/spec/utility_spec.rb

@@ -46,11 +46,22 @@ describe Palimpsest::Utility do
   describe "write" do
 
     let(:file) { double File }
+    let(:mtime) { Time.now }
 
-    it "writes to file" do
+    before :each do
       allow(File).to receive(:open).with('path/to/file', 'w').and_yield(file)
+    end
+
+    it "writes to file" do
       expect(file).to receive(:write).with('data')
       Palimpsest::Utility.write 'data', 'path/to/file'
     end
+
+    it "can preserve atime and mtime" do
+      allow(file).to receive(:write)
+      allow(File).to receive(:mtime).with('path/to/file').and_return(mtime)
+      expect(File).to receive(:utime).with(mtime, mtime, 'path/to/file')
+      Palimpsest::Utility.write 'data', 'path/to/file', preserve: true
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: palimpsest
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Evan Boyd Sosenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-25 00:00:00.000000000 Z
+date: 2013-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -255,12 +255,17 @@ files:
 - Rakefile
 - lib/palimpsest.rb
 - lib/palimpsest/assets.rb
+- lib/palimpsest/component.rb
 - lib/palimpsest/environment.rb
+- lib/palimpsest/external.rb
+- lib/palimpsest/site.rb
 - lib/palimpsest/utility.rb
 - lib/palimpsest/version.rb
 - palimpsest.gemspec
 - spec/assets_spec.rb
+- spec/component_spec.rb
 - spec/environment_spec.rb
+- spec/external_spec.rb
 - spec/spec_helper.rb
 - spec/utility_spec.rb
 homepage: https://github.com/razor-x/palimpsest
@@ -291,7 +296,9 @@ summary: Built flexible, simple, and customizable. Palimpsest runs on top of any
   and easy integration with Kit.
 test_files:
 - spec/assets_spec.rb
+- spec/component_spec.rb
 - spec/environment_spec.rb
+- spec/external_spec.rb
 - spec/spec_helper.rb
 - spec/utility_spec.rb
 has_rdoc: