torba 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c693882d1f37d1cdf2ea156a9d6fd90aaa42409e
+  data.tar.gz: d57f3ec19cf7274292a3bee7440f9102ddd2e3a6
+SHA512:
+  metadata.gz: 3191c0a6b2610b78e148fe7f3cbf936f8fd3a82707e62d914c01378ea464bee951b3d6412530089792d10188fba62faa633b52a0ec81e72f1506f548c9418af5
+  data.tar.gz: aa2e6571108e54d3fc76d35e99e5b8d90f23e47ee70c8dd456d7e3aa6cfb06831d6ad5e821b72c0c746f3f80c4b463a0d19e0c2a61c7acb8968b731b0a1c929f

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - jruby-19mode
+  - rbx-2
+bundler_args: --without doc debug

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+## Adding a feature
+
+1. Open an issue and explain what you're planning to do. It is better to discuss new idea first,
+   rather when diving into code.
+2. Add some tests.
+3. Write the code.
+4. Make sure all tests pass.
+5. Commit with detailed explanation what you've done in a message.
+6. Open pull request.
+
+## Breaking/removing a feature
+
+1. Add deprecation warning and fallback to old behaivour if possible.
+2. Explain how to migrate to the new code in CHANGELOG.
+3. Update/remove tests.
+4. Update the code.
+5. Make sure all tests pass.
+6. Commit with detailed explanation what you've done in a message.
+7. Open pull request.
+
+## Fixing a bug
+
+1. Add failing test.
+2. Fix the bug.
+3. Make sure all tests pass.
+4. Commit with detailed explanation what you've done in a message.
+5. Open pull request.
+
+## Fixing a typo
+
+1. Commit with a message that include "[ci skip]" remark.
+2. Open pull request.
+
+## Running the tests
+
+```
+rake test
+```
+
+## Working with documentation
+
+```
+yard server -dr
+open http://localhost:8808
+```

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem "pry", :group => :debug
+gem "yard", "~> 0.8", :group => :doc

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Andrii Malyshko
+
+MIT License
+
+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/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+task :default => :test
+task :test do
+  $LOAD_PATH.unshift("test")
+  Dir.glob("./test/**/*_test.rb").each { |file| require file}
+end

data/Readme.md

@@ -0,0 +1,211 @@
+# Torba
+
+[![Build Status](https://img.shields.io/travis/torba-rb/torba.svg)](https://travis-ci.org/torba-rb/torba)
+[![Gem version](https://img.shields.io/gem/v/torba.svg)](https://rubygems.org/gems/torba)
+
+**Torba** is a [Bower][bower]-less asset manager for [Sprockets][sprockets]. It makes a local copy
+of a JS/CSS library and puts it under Sprockets' [load path][sprockets-load-path].
+
+## Name origin
+
+"Торба" [[tǒːrba][torba-pronounce]] in Ukrainian and "torba" in Polish, Turkic languages can mean
+"duffel bag", "gunny sack" or, more generally, any flexible container.
+
+## Status
+
+Not tested in production.
+
+## Documentation
+
+http://rubydoc.info/github/torba-rb/torba/
+
+## Why
+
+De facto approach, i.e. wrapping JS and CSS libraries in a gem, requires from a
+maintainer to constantly track changes in upstream repository. Even more, if the
+maintainer stops using this gem itself, it will eventually become abandoned.
+Many libraries still have no gem wrappers.
+
+Among other alternatives:
+
+* [rails-assets][rails-assets] project relies on Bower *and* it is quite complex,
+* [bower-rails][bower-rails] project relies on Bower.
+
+Problems with the Bower:
+
+* it is not a part of Ruby ecosystem,
+* frontend JS libraries are usually standalone (except for jQuery dependency), so there's
+  no need for complex Bundler-like solution with tree-dependency resolution,
+* often we can't use optimistic version constraints, because JS community still doesn't
+  fully grasp the idea of [Semver][semver]. By specifying strict versions we use Bower
+  as a complex facade for functionality that could be done by curl.
+
+## External dependencies
+
+* curl
+* unzip
+
+## Design limitations
+
+* Torba doesn't do any version dependency resolution, it's up to you to specify correct version of
+  each asset package,
+* Torba doesn't do any builds, use remote sources with pre-built assets.
+
+## Installation
+
+Add this line to your application's Gemfile and run `bundle`:
+
+```ruby
+gem 'torba'
+```
+
+### Rails
+
+in boot.rb
+
+```diff
+ require 'bundler/setup' # Set up gems listed in the Gemfile.
++require 'torba/verify'
+```
+
+it config/application.rb
+
+```diff
+ # Require the gems listed in Gemfile, including any gems
+ # you've limited to :test, :development, or :production.
+ Bundler.require(*Rails.groups)
++
++require 'torba/rails'
+```
+
+## Usage
+
+1. Create Torbafile at the project root and commit it.
+
+2. Run `bundle exec torba pack`.
+
+3. Add "require" [Sprockets directives][sprockets-directives] to your "application.js"
+and/or "@import" [Sass directives][sass-import] to "application.css".
+
+If any changes made to the Torbafile, run `bundle exec torba pack` again.
+
+### Torbafile
+
+Torbafile is an assets specification. It is a plain text file that contains one or more
+sections, each of them describes one remote source of assets.
+
+Currently only zip archives and [Github releases][github-releases] are supported.
+
+#### Zip archive package
+
+Allows to download and unpack asset package from any source accessible by curl.
+
+The syntax is:
+
+```
+zip "name", url: "..." [, import: %w(...)]
+```
+
+where "name" is an arbitrary name for the package, more on "import" below. For example,
+
+```
+zip "scroll_magic", url: "https://github.com/janpaepke/ScrollMagic/archive/v2.0.0.zip"
+```
+
+#### Github release package
+
+This is a more readable version/shortcut for "https://github.com/.../archive/..." URLs.
+
+The syntax is:
+
+```
+gh_release "name", source: "...", tag: "..." [, import: %w(...)]
+```
+
+where "source" is the user + repository and "tag" is the repository tag (exactly as on Github,
+i.e. with "v" prefix if present), more on "import" below. For example,
+
+```
+gh_release "scroll_magic", source: "janpaepke/ScrollMagic", tag: "v.2.0.0"
+```
+
+### "Packing the torba" process
+
+When you run `torba pack` the following happens:
+
+1.  All remote sources are cached locally.
+
+2.  Archives are unpacked with top level directory removed. This is done for good cause it
+usually contains package version, e.g. "react-0.13.2", and you don't want to reference versions
+inside your application code (except Torbafile).
+
+3.  Remote source's content is copied as is to the `Torba.home_path` location with **package name used
+as a namespace**.
+
+    This is also done for good in order to avoid name collisions (since many JS projects can have
+assets with the same names and all packages are placed into shared Sprockets' virtual filesystem).
+The downside is that you have to use namespace in each require directive, which can lead to
+duplication:
+
+    ```javascript
+    // application.js
+    //= require 'underscore/underscore'
+    ```
+
+    Hint: use "require_directory" if you strongly against such duplication:
+
+    ```javascript
+    //= require_directory 'underscore'
+    ```
+
+4.  Stylesheets (if any) are converted to ".css.erb" with "asset_path" helpers used in "url(...)"
+statements.
+
+### :import option
+
+Copying whole remote source's content has one disadvantage of using remote source specific paths in your
+require/import directives. For example, if an archive contains file in "dist/css" directory, you'll have
+to mention it:
+
+```css
+/* application.css */
+@import 'lightslider/dist/css/lightslider';
+```
+
+To mitigate this you can cherry-pick files from the source via "import" option, for example:
+
+```
+gh_release "lightslider", source: "sachinchoolur/lightslider", tag: "1.1.2", import: %w[
+  dist/css/lightslider.css
+]
+```
+
+Such files will be copied directly to the package root (i.e. file tree becomes flatten), thus you
+can omit unnesseccary paths:
+
+```css
+@import 'lightslider/lightslider';
+```
+
+You can use any Dir.glob pattern:
+
+```
+gh_release "lightslider", source: "sachinchoolur/lightslider", tag: "1.1.2", import: %w[
+  dist/css/lightslider.css
+  dist/img/*.png
+]
+```
+
+In addition to this "path/" is treated as a shortcut for "path/**/*" glob pattern.
+
+
+[bower]: http://bower.io/
+[sprockets]: https://github.com/sstephenson/sprockets/
+[sprockets-load-path]: https://github.com/sstephenson/sprockets#the-load-path
+[torba-pronounce]: http://upload.wikimedia.org/wikipedia/commons/2/28/Uk-%D1%82%D0%BE%D1%80%D0%B1%D0%B0.ogg
+[github-releases]: https://help.github.com/articles/about-releases/
+[sprockets-directives]: https://github.com/sstephenson/sprockets#the-directive-processor
+[sass-import]: http://sass-lang.com/documentation/file.SASS_REFERENCE.html#import
+[rails-assets]: https://rails-assets.org/
+[bower-rails]: https://github.com/rharriso/bower-rails
+[semver]: http://semver.org/

data/bin/torba

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "torba/cli"
+
+Torba::Cli.start

data/lib/torba/cli.rb

@@ -0,0 +1,18 @@
+require "thor"
+require "torba"
+
+module Torba
+  class Cli < Thor
+    desc "pack", "download and prepare all packages defined in Torbafile"
+    def pack
+      Torba.pretty_errors { Torba.pack }
+      Torba.ui.confirm "Torba has been packed!"
+    end
+
+    desc "verify", "check if all packages are prepared"
+    def verify
+      Torba.pretty_errors { Torba.verify }
+      Torba.ui.confirm "Torba is prepared!"
+    end
+  end
+end

data/lib/torba/css_url_to_erb_asset_path.rb

@@ -0,0 +1,51 @@
+module Torba
+  # Parses content of CSS file and converts its image assets paths into Sprockets'
+  # {https://github.com/sstephenson/sprockets#logical-paths logical paths}.
+  class CssUrlToErbAssetPath
+    URL_RE =
+      /
+        url\(     # url(
+        \s*       # optional space
+        (?!data)  # no data URIs
+        ['"]?     # optional quote
+        (?!\/)    # only relative location
+        ([^'"]+?) # location
+        ['"]?     # optional quote
+        \s*       # optional space
+        \)        # )
+      /xm
+
+    # @return [String] CSS file content where image "url(...)" paths are replaced by ERB
+    #   interpolations "url(<%= asset_path(...) %>)".
+    # @param content [String] content of original CSS file
+    # @param file_path [String] absolute path to original CSS file
+    # @yield [image_file_path]
+    # @yieldparam image_file_path [String] absolute path to original image file which is mentioned
+    #   within CSS file
+    # @yieldreturn [String] logical path to image file within Sprockets' virtual filesystem.
+    #
+    # @example
+    #   content = \
+    #     ".react-toolbar {
+    #       width: 100%;
+    #       background: url('./images/toolbar.png');
+    #     }"
+    #
+    #   new_content = CssUrlToErbAssetPath.call(content, "/var/downloads/react_unzipped/styles.css") do |url|
+    #     url.sub("/var/downloads/react_unzipped/images", "react-toolbar-js"
+    #   end
+    #
+    #   new_content #=>
+    #     ".react-toolbar {
+    #       width: 100%;
+    #       background: url('<%= asset_path('react-toolbar-js/toolbar.png') %>');
+    #     }"
+    def self.call(content, file_path)
+      content.gsub(URL_RE) do
+        absolute_image_file_path = File.expand_path($1, File.dirname(file_path))
+        sprockets_file_path = yield absolute_image_file_path
+        "url('<%= asset_path('#{sprockets_file_path}') %>')"
+      end
+    end
+  end
+end

data/lib/torba/import_list.rb

@@ -0,0 +1,38 @@
+module Torba
+  module Errors
+    AssetNotFound = Class.new(StandardError)
+  end
+
+  # Represents a list of assets to be imported from a remote source.
+  class ImportList
+    class Asset < Struct.new(:absolute_path, :subpath)
+      def css?
+        absolute_path.end_with?(".css")
+      end
+    end
+
+    # @return [Array<Asset>] full list of assets to be imported.
+    attr_reader :assets
+
+    def initialize(assets)
+      @assets = assets
+    end
+
+    # @return [Asset] asset with given path.
+    # @param path [String] absolute path of an asset.
+    # @raise [Errors::AssetNotFound] if nothing found
+    def find_by_absolute_path(path)
+      assets.find { |asset| asset.absolute_path == path } || raise(Errors::AssetNotFound.new(path))
+    end
+
+    # @return [Array<Asset>] list of stylesheets to be imported.
+    def css_assets
+      assets.find_all { |asset| asset.css? }
+    end
+
+    # @return [Array<Asset>] list of assets to be imported except stylesheets.
+    def non_css_assets
+      assets.find_all { |asset| !asset.css? }
+    end
+  end
+end

data/lib/torba/manifest.rb

@@ -0,0 +1,65 @@
+require "torba/package"
+require "torba/remote_sources/zip"
+require "torba/remote_sources/github_release"
+
+module Torba
+  # Represents Torbafile.
+  class Manifest
+    # all packages defined in Torbafile
+    attr_reader :packages
+
+    # Reads Torbafile and evaluates it.
+    # @return [Manifest]
+    #
+    # @overload self.build(file_path)
+    #   @param file_path [String] absolute path to Torbafile
+    #
+    # @overload self.build
+    #   Reads Torbafile from current directory
+    def self.build(file_path = nil)
+      file_path ||= File.join(Dir.pwd, "Torbafile")
+
+      manifest = new
+      content = File.read(file_path)
+      manifest.instance_eval(content, file_path)
+      manifest
+    end
+
+    def initialize
+      @packages = []
+    end
+
+    # Adds {Package} with {RemoteSources::Zip} to {#packages}
+    def zip(name, options = {})
+      url = options.fetch(:url)
+      remote_source = RemoteSources::Zip.new(url)
+      packages << Package.new(name, remote_source, options)
+    end
+
+    # Adds {Package} with {RemoteSources::GithubRelease} to {#packages}
+    def gh_release(name, options = {})
+      source = options.fetch(:source)
+      tag = options.fetch(:tag)
+      remote_source = RemoteSources::GithubRelease.new(source, tag)
+      packages << Package.new(name, remote_source, options)
+    end
+
+    # Builds all {#packages}
+    # @return [void]
+    def pack
+      packages.each(&:build)
+    end
+
+    # @return [Array<String>] list of paths to each prepared asset package.
+    #   It should be appended to the Sprockets' load_path.
+    def load_path
+      packages.map(&:load_path)
+    end
+
+    # Verifies all {#packages}
+    # @return [void]
+    def verify
+      packages.each(&:verify)
+    end
+  end
+end

data/lib/torba/package.rb

@@ -0,0 +1,173 @@
+require "fileutils"
+
+require "torba/css_url_to_erb_asset_path"
+require "torba/import_list"
+
+module Torba
+  module Errors
+    UnbuiltPackage = Class.new(StandardError)
+
+    class NothingToImport < StandardError
+      attr_reader :package, :path
+
+      def initialize(options)
+        @package = options.fetch(:package)
+        @path = options.fetch(:path)
+        super
+      end
+    end
+  end
+
+  # Represents remote source with explicit paths/files to be imported (i.e.
+  # copied from an archive, git repository etc).
+  # Stylesheets (if any) are treated specially because static "url(...)"
+  # definitions should be replaced with Sprockets-aware "asset_path" helpers.
+  class Package
+    # @return [String] short package name, acts as as namespace within Sprockets' load path.
+    #   Doesn't need to be equal to remote package name.
+    attr_reader :name
+
+    # @return instance that implements {RemoteSources::Common}
+    attr_reader :remote_source
+
+    # @return [Array<String>] list of file paths to import (relative to remote source root).
+    # @example Direct path to a file
+    #   ["build/underscore.js"]
+    # @example {http://www.rubydoc.info/stdlib/core/Dir#glob-class_method Dir.glob} pattern
+    #   ["build/*.js", "**/*.css"]
+    # @example Any file within directory (including subdirectories)
+    #   ["build/"] # same as ["build/**/*"]
+    attr_reader :import_paths
+
+    # @param name [String] see {#name}
+    # @param remote_source [#[]] see {#remote_source}
+    # @param options [Hash]
+    # @option options [Array<String>] :import list assigned to {#import_paths}
+    def initialize(name, remote_source, options = {})
+      @name = name
+      @remote_source = remote_source
+      @import_paths = (options[:import] || ["**/*"]).sort.map do |path|
+        if path.end_with?("/")
+          File.join(path, "**/*")
+        else
+          path
+        end
+      end
+    end
+
+    # @raise [Errors::UnbuiltPackage] if package is not build.
+    def verify
+      raise Errors::UnbuiltPackage.new(name) unless built?
+    end
+
+    # Cache remote source and import specified assets to {#load_path}.
+    # @return [void]
+    # @note Directories explicitly specified in {#import_paths} are not preserved after importing,
+    #   i.e. resulted file tree becomes flatten. This way you can omit build specific directories
+    #   when requiring assets in your project. If you want to preserve remote source file tree,
+    #   use glob patterns without mentioning subdirectories in them.
+    #
+    #   In addition {#name} is used as a namespace folder within {#load_path} to protect file names
+    #   clashing across packages.
+    #
+    #     package.name #=> "datepicker"
+    #     package.import_paths #=> ["css/stylesheet.css", "js/*.js"]
+    #     Dir[package.load_path + "/**/*"] #=> ["datepicker/stylesheet.css", "datepicker/script.js"]
+    #
+    #     package.name #=> "datepicker"
+    #     package.import_paths #=> ["**/*.{js,css}"]
+    #     Dir[package.load_path + "/**/*"] #=> ["datepicker/css/stylesheet.css", "datepicker/js/script.js"]
+    def build
+      return if built?
+      process_stylesheets
+      process_other_assets
+    rescue
+      remove
+      raise
+    end
+
+    # @return [String] path where processed files of the package reside. It's located within
+    #   {Torba.home_path} directory.
+    def load_path
+      @load_path ||= File.join(Torba.home_path, folder_name)
+    end
+
+    # @return [ImportList]
+    def import_list
+      @import_list ||= build_import_list
+    end
+
+    # Remove self from filesystem.
+    # @return [void]
+    def remove
+      FileUtils.rm_rf(load_path)
+    end
+
+    private
+
+    def built?
+      Dir.exist?(load_path)
+    end
+
+    def folder_name
+      digest = Torba.digest(import_paths.join << remote_source.digest)
+      "#{name}-#{digest}"
+    end
+
+    def build_import_list
+      assets = import_paths.flat_map do |import_path|
+        path_wo_glob_metacharacters = import_path.sub(/\*.+$/, "")
+
+        assets = remote_source[import_path].map do |absolute_path, relative_path|
+          subpath =
+            if relative_path == import_path
+              File.basename(relative_path)
+            else
+              relative_path.sub(path_wo_glob_metacharacters, "")
+            end
+
+          ImportList::Asset.new(absolute_path, subpath)
+        end
+
+        if assets.empty?
+          raise Errors::NothingToImport.new(package: name, path: import_path)
+        end
+
+        assets
+      end
+
+      ImportList.new(assets)
+    end
+
+    def process_stylesheets
+      import_list.css_assets.each do |asset|
+        content = File.read(asset.absolute_path)
+
+        new_content = CssUrlToErbAssetPath.call(content, asset.absolute_path) do |image_file_path|
+          image_asset = import_list.find_by_absolute_path(image_file_path)
+          with_namespace(image_asset.subpath)
+        end
+
+        new_absolute_path = File.join(load_path, with_namespace(asset.subpath + ".erb"))
+        ensure_directory(new_absolute_path)
+        File.write(new_absolute_path, new_content)
+      end
+    end
+
+    def process_other_assets
+      import_list.non_css_assets.each do |asset|
+        new_absolute_path = File.join(load_path, with_namespace(asset.subpath))
+        ensure_directory(new_absolute_path)
+        FileUtils.cp(asset.absolute_path, new_absolute_path)
+      end
+    end
+
+    def with_namespace(file_name)
+      File.join(name, file_name)
+    end
+
+    def ensure_directory(file)
+      FileUtils.mkdir_p(File.dirname(file))
+    end
+  end
+end