lotus-assets 0.0.0 → 0.1.0

data/bin/lotus-assets

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'pathname'
+
+options = {}
+OptionParser.new do |opts|
+  opts.banner = "Usage: lotus-assets --config=path/to/config.rb"
+
+  opts.on("-c", "--config FILE", "Path to config") do |c|
+    options[:config] = c
+  end
+end.parse!
+
+config = options.fetch(:config) { raise ArgumentError.new("You must specify a configuration file") }
+config = Pathname.new(config)
+config.exist? or raise ArgumentError.new("Cannot find configuration file: #{ config }")
+
+require 'lotus/assets'
+load config
+
+Lotus::Assets.deploy

data/lib/lotus/assets.rb

@@ -1,7 +1,158 @@
-require "lotus/assets/version"
+require 'thread'
+require 'lotus/utils/class_attribute'
 
 module Lotus
+  # Assets management for Ruby web applications
+  #
+  # @since 0.1.0
   module Assets
-    # Your code goes here...
+    # Base error for Lotus::Assets
+    #
+    # All the errors defined in this framework MUST inherit from it.
+    #
+    # @since 0.1.0
+    class Error < ::StandardError
+    end
+
+    require 'lotus/assets/version'
+    require 'lotus/assets/configuration'
+    require 'lotus/assets/config/global_sources'
+    require 'lotus/assets/helpers'
+
+    include Utils::ClassAttribute
+
+    # Configuration
+    #
+    # @since 0.1.0
+    # @api private
+    class_attribute :configuration
+    self.configuration = Configuration.new
+
+    # Configure framework
+    #
+    # @param blk [Proc] configuration code block
+    #
+    # @return self
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Assets::Configuration
+    def self.configure(&blk)
+      configuration.instance_eval(&blk)
+      self
+    end
+
+    # Prepare assets for deploys
+    #
+    # @since 0.1.0
+    def self.deploy
+      require 'lotus/assets/precompiler'
+      require 'lotus/assets/bundler'
+
+      Precompiler.new(configuration, duplicates).run
+      Bundler.new(configuration,     duplicates).run
+    end
+
+    # Preload the framework
+    #
+    # This MUST be used in production mode
+    #
+    # @since 0.1.0
+    #
+    # @example Direct Invocation
+    #   require 'lotus/assets'
+    #
+    #   Lotus::Assets.load!
+    #
+    # @example Load Via Configuration Block
+    #   require 'lotus/assets'
+    #
+    #   Lotus::Assets.configure do
+    #     # ...
+    #   end.load!
+    def self.load!
+      configuration.load!
+    end
+
+    # Global assets sources
+    #
+    # This is designed for third party integration gems with frontend frameworks
+    # like Bootstrap, Ember.js or React.
+    #
+    # Developers can maintain gems that ship static assets for these frameworks
+    # and make them available to Lotus::Assets.
+    #
+    # @return [Lotus::Assets::Config::GlobalSources]
+    #
+    # @since 0.1.0
+    #
+    # @example Ember.js Integration
+    #   # lib/lotus/emberjs.rb (third party gem)
+    #   require 'lotus/assets'
+    #
+    #   Lotus::Assets.sources << '/path/to/emberjs/assets'
+    def self.sources
+      synchronize do
+        @@sources ||= Config::GlobalSources.new
+      end
+    end
+
+    # Duplicate the framework and generate modules for the target application
+    #
+    # @param mod [Module] the Ruby namespace of the application
+    # @param blk [Proc] an optional block to configure the framework
+    #
+    # @return [Module] a copy of Lotus::Assets
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Assets#dupe
+    # @see Lotus::Assets::Configuration
+    def self.duplicate(mod, &blk)
+      dupe.tap do |duplicated|
+        duplicated.configure(&blk) if block_given?
+        duplicates << duplicated
+      end
+    end
+
+    # Duplicate Lotus::Assets in order to create a new separated instance
+    # of the framework.
+    #
+    # The new instance of the framework will be completely decoupled from the
+    # original. It will inherit the configuration, but all the changes that
+    # happen after the duplication, won't be reflected on the other copies.
+    #
+    # @return [Module] a copy of Lotus::Assets
+    #
+    # @since 0.1.0
+    # @api private
+    def self.dupe
+      dup.tap do |duplicated|
+        duplicated.configuration = configuration.duplicate
+      end
+    end
+
+    # Keep track of duplicated frameworks
+    #
+    # @return [Array] a collection of duplicated frameworks
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see Lotus::Assets#duplicate
+    # @see Lotus::Assets#dupe
+    def self.duplicates
+      synchronize do
+        @@duplicates ||= Array.new
+      end
+    end
+
+    private
+
+    # @since 0.1.0
+    # @api private
+    def self.synchronize(&blk)
+      Mutex.new.synchronize(&blk)
+    end
   end
 end

data/lib/lotus/assets/bundler.rb

@@ -0,0 +1,173 @@
+require 'digest'
+require 'fileutils'
+require 'json'
+
+module Lotus
+  module Assets
+    # Bundle assets from a single application.
+    #
+    # @since 0.1.0
+    # @api private
+    class Bundler
+      # @since 0.1.0
+      # @api private
+      DEFAULT_PERMISSIONS = 0644
+
+      # @since 0.1.0
+      # @api private
+      JAVASCRIPT_EXT      = '.js'.freeze
+
+      # @since 0.1.0
+      # @api private
+      STYLESHEET_EXT      = '.css'.freeze
+
+      # @since 0.1.0
+      # @api private
+      WILDCARD_EXT        = '.*'.freeze
+
+      # @since 0.1.0
+      # @api private
+      URL_SEPARATOR       = '/'.freeze
+
+      # @since 0.1.0
+      # @api private
+      URL_REPLACEMENT     = ''.freeze
+
+      # Return a new instance
+      #
+      # @param configuration [Lotus::Assets::Configuration] a single application configuration
+      #
+      # @param duplicates [Array<Lotus::Assets>] the duplicated frameworks
+      #   (one for each application)
+      #
+      # @return [Lotus::Assets::Bundler] a new instance
+      #
+      # @since 0.1.0
+      # @api private
+      def initialize(configuration, duplicates)
+        @manifest       = Hash.new
+        @configuration  = configuration
+        @configurations = if duplicates.empty?
+                            [@configuration]
+                          else
+                            duplicates.map(&:configuration)
+                          end
+      end
+
+      # Start the process.
+      #
+      # For each asset contained in the sources and third party gems, it will:
+      #
+      #   * Compress
+      #   * Create a checksum version
+      #
+      # At the end it will generate a digest manifest
+      #
+      # @see Lotus::Assets::Configuration#digest
+      # @see Lotus::Assets::Configuration#manifest
+      # @see Lotus::Assets::Configuration#manifest_path
+      def run
+        assets.each do |asset|
+          next if ::File.directory?(asset)
+
+          compress(asset)
+          checksum(asset)
+        end
+
+        generate_manifest
+      end
+
+      private
+
+      # @since 0.1.0
+      # @api private
+      def assets
+        Dir.glob("#{ public_directory }#{ ::File::SEPARATOR }**#{ ::File::SEPARATOR }*")
+      end
+
+      # @since 0.1.0
+      # @api private
+      def compress(asset)
+        case File.extname(asset)
+        when JAVASCRIPT_EXT then _compress(compressor(:js, asset),  asset)
+        when STYLESHEET_EXT then _compress(compressor(:css, asset), asset)
+        end
+      end
+
+      # @since 0.1.0
+      # @api private
+      def checksum(asset)
+        digest        = Digest::MD5.file(asset)
+        filename, ext = ::File.basename(asset, WILDCARD_EXT), ::File.extname(asset)
+        directory     = ::File.dirname(asset)
+        target        = [directory, "#{ filename }-#{ digest }#{ ext }"].join(::File::SEPARATOR)
+
+        FileUtils.cp(asset, target)
+        _set_permissions(target)
+
+        store_manifest(asset, target)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def generate_manifest
+        _write(@configuration.manifest_path, JSON.dump(@manifest))
+      end
+
+      # @since 0.1.0
+      # @api private
+      def store_manifest(asset, target)
+        @manifest[_convert_to_url(::File.expand_path(asset))] = _convert_to_url(::File.expand_path(target))
+      end
+
+      # @since 0.1.0
+      # @api private
+      def compressor(type, asset)
+        _configuration_for(asset).__send__(:"#{ type }_compressor")
+      end
+
+      # @since 0.1.0
+      # @api private
+      def _compress(compressor, asset)
+        _write(asset, compressor.compress(asset))
+      rescue => e
+        warn "Skipping compression of: `#{ asset }'\nReason: #{ e }\n\t#{ e.backtrace.join("\n\t") }\n\n"
+      end
+
+      # @since 0.1.0
+      # @api private
+      def _convert_to_url(path)
+        path.sub(public_directory.to_s, URL_REPLACEMENT).
+          gsub(File::SEPARATOR, URL_SEPARATOR)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def _write(path, content)
+        Pathname.new(path).dirname.mkpath
+        ::File.write(path, content)
+
+        _set_permissions(path)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def _set_permissions(path)
+        ::File.chmod(DEFAULT_PERMISSIONS, path)
+      end
+
+      def _configuration_for(asset)
+        url = _convert_to_url(asset)
+
+        @configurations.find {|config| url.start_with?(config.prefix) } ||
+          @configuration
+      end
+
+      # @since 0.1.0
+      # @api private
+      def public_directory
+        @configuration.public_directory
+      end
+    end
+  end
+end

data/lib/lotus/assets/cache.rb

@@ -0,0 +1,58 @@
+require 'thread'
+
+module Lotus
+  module Assets
+    # Store assets references when compile mode is on.
+    #
+    # This is expecially useful in development mode, where we want to compile
+    # only the assets that were changed from last browser refresh.
+    #
+    # @since 0.1.0
+    # @api private
+    class Cache
+      # Return a new instance
+      #
+      # @return [Lotus::Assets::Cache] a new instance
+      def initialize
+        @data  = Hash.new{|h,k| h[k] = 0 }
+        @mutex = Mutex.new
+      end
+
+      # Check if the given file is fresh or changed from last check.
+      #
+      # @param file [String,Pathname] the file path
+      #
+      # @return [TrueClass,FalseClass] the result of the check
+      #
+      # @since 0.1.0
+      # @api private
+      def fresh?(file)
+        @mutex.synchronize do
+          @data[file.to_s] < mtime(file)
+        end
+      end
+
+      # Store the given file reference
+      #
+      # @param file [String,Pathname] the file path
+      #
+      # @return [TrueClass,FalseClass] the result of the check
+      #
+      # @since 0.1.0
+      # @api private
+      def store(file)
+        @mutex.synchronize do
+          @data[file.to_s] = mtime(file)
+        end
+      end
+
+      private
+
+      # @since 0.1.0
+      # @api private
+      def mtime(file)
+        file.mtime.utc.to_i
+      end
+    end
+  end
+end

data/lib/lotus/assets/compiler.rb

@@ -0,0 +1,212 @@
+module Lotus
+  module Assets
+    class MissingAsset < Error
+      def initialize(name, sources)
+        sources = sources.map(&:to_s).join(', ')
+        super("Missing asset: `#{ name }' (sources: #{ sources })")
+      end
+    end
+
+    class UnknownAssetEngine < Error
+      def initialize(source)
+        super("No asset engine registered for `#{ ::File.basename(source) }'")
+      end
+    end
+
+    # Assets compiler
+    #
+    # It compiles assets that needs to be preprocessed (eg. Sass or ES6) into
+    # the destination directory.
+    #
+    # Vanilla javascripts or stylesheets are just copied over.
+    #
+    # @since 0.1.0
+    # @api private
+    class Compiler
+      # @since 0.1.0
+      # @api private
+      DEFAULT_PERMISSIONS = 0644
+
+      # @since 0.1.0
+      # @api private
+      COMPILE_PATTERN = '*.*.*'.freeze # Example hello.js.es6
+
+      # @since 0.1.0
+      # @api private
+      EXTENSIONS = {'.js' => true, '.css' => true}.freeze
+
+      # @since 0.1.0
+      # @api private
+      SASS_CACHE_LOCATION = Pathname(Lotus.respond_to?(:root) ?
+                                     Lotus.root : Dir.pwd).join('tmp', 'sass-cache')
+
+      # Compile the given asset
+      #
+      # @param configuration [Lotus::Assets::Configuration] the application
+      #   configuration associated with the given asset
+      #
+      # @param name [String] the asset path
+      #
+      # @since 0.1.0
+      # @api private
+      def self.compile(configuration, name)
+        return unless configuration.compile
+
+        require 'tilt'
+        require 'lotus/assets/cache'
+        new(configuration, name).compile
+      end
+
+      # Assets cache
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @see Lotus::Assets::Cache
+      def self.cache
+        @@cache ||= Assets::Cache.new
+      end
+
+      # Return a new instance
+      #
+      # @param configuration [Lotus::Assets::Configuration] the application
+      #   configuration associated with the given asset
+      #
+      # @param name [String] the asset path
+      #
+      # @return [Lotus::Assets::Compiler] a new instance
+      #
+      # @since 0.1.0
+      # @api private
+      def initialize(configuration, name)
+        @configuration = configuration
+        @name          = Pathname.new(name)
+      end
+
+      # Compile the asset
+      #
+      # @raise [Lotus::Assets::MissingAsset] if the asset can't be found in
+      #   sources
+      #
+      # @since 0.1.0
+      # @api private
+      def compile
+        raise MissingAsset.new(@name, @configuration.sources) unless exist?
+        return unless fresh?
+
+        if compile?
+          compile!
+        else
+          copy!
+        end
+
+        cache!
+      end
+
+      private
+
+      # @since 0.1.0
+      # @api private
+      def source
+        @source ||= begin
+          @name.absolute? ? @name :
+            @configuration.find(@name)
+        end
+      end
+
+      # @since 0.1.0
+      # @api private
+      def destination
+        @destination ||= @configuration.destination_directory.join(basename)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def basename
+        result = ::File.basename(@name)
+
+        if compile?
+          result.scan(/\A[[[:alnum:]][\-\_]]*\.[[\w]]*/).first || result
+        else
+          result
+        end
+      end
+
+      # @since 0.1.0
+      # @api private
+      def exist?
+        !source.nil? &&
+          source.exist?
+      end
+
+      # @since 0.1.0
+      # @api private
+      def fresh?
+        !destination.exist? ||
+          cache.fresh?(source)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def compile?
+        @compile ||= ::File.fnmatch(COMPILE_PATTERN, source.to_s) &&
+          !EXTENSIONS[::File.extname(source.to_s)]
+      end
+
+      # @since 0.1.0
+      # @api private
+      def compile!
+        # NOTE `:load_paths' is useful only for Sass engine, to make `@include' directive to work.
+        # For now we don't want to maintan a specialized Compiler version for Sass.
+        #
+        # If in the future other precompilers will need special treatment,
+        # we can consider to maintain several specialized versions in order to
+        # don't add a perf tax to all the other preprocessors who "just work".
+        #
+        # Example: if Less "just works", we can keep it in the general `Compiler',
+        # but have a `SassCompiler` if it requires more than `:load_paths'.
+        #
+        # NOTE: We need another option to pass for Sass: `:cache_location'.
+        #
+        # This is needed to don't create a `.sass-cache' directory at the root of the project,
+        # but to have it under `tmp/sass-cache'.
+        write { Tilt.new(source, nil, load_paths: @configuration.sources.to_a, cache_location: sass_cache_location).render }
+      rescue RuntimeError
+        raise UnknownAssetEngine.new(source)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def copy!
+        write { source.read }
+      end
+
+      # @since 0.1.0
+      # @api private
+      def cache!
+        cache.store(source)
+      end
+
+      # @since 0.1.0
+      # @api private
+      def write
+        destination.dirname.mkpath
+        destination.open(File::WRONLY|File::CREAT, DEFAULT_PERMISSIONS) do |file|
+          file.write(yield)
+        end
+      end
+
+      # @since 0.1.0
+      # @api private
+      def cache
+        self.class.cache
+      end
+
+      # @since 0.1.0
+      # @api private
+      def sass_cache_location
+        SASS_CACHE_LOCATION
+      end
+    end
+  end
+end