jsus 0.3.1 → 0.3.2

data/.document

@@ -1,5 +1,5 @@
 lib/**/*.rb
 bin/*
-- 
+-
 features/**/*.feature
 LICENSE.txt

data/.travis.yml

@@ -1,4 +1,4 @@
-script: "rake"
+script: "bundle exec rake"
 rvm:
   - 1.8.7
   - 1.9.2

data/.yardopts

@@ -0,0 +1,9 @@
+--markup="markdown" lib/**/*.rb
+--no-private
+--no-protected
+--main README.md
+--hide-tag todo
+-
+LICENSE
+CHANGELOG
+docs/*.textile

data/CHANGELOG

@@ -1,4 +1,25 @@
 = Jsus Changelog
+== Version 0.3.2
+Middleware changes:
+* Fixed minor problem with middleware when package name and source file tag
+  are the same
+* Settings are now shared between Jsus::Middleware and subclasses
+* Middleware now also supports /include/ directive (generates includes file),
+  like -g option of CLI utility
+* Hack for cache output paths to be recognizable by nginx
+
+CLI changes:
+* --very-verbose mode, outputs tree of your packages, very useful when debugging
+  missing dependencies.
+* If you have circular dependencies in your code, jsus will detect them and issue
+  a huge warning message (WIP)
+
+Shared changes:
+* Pool instantiation will now follow symlinks one level deep
+* Somewhat easier on eyes murdoc template
+* Pool instantiation now also accepts array of directories as its argument
+* YARD docs are now the default docs choice
+
 == Version 0.3.1
 * Added wildcard support for Jsus::Middleware
 

data/Gemfile

@@ -6,7 +6,7 @@ gem "json_pure"
 gem "rgl"
 
 group :development do
-  gem "bundler"
+  gem "rake"
   gem "rspec"
   gem "cucumber"
   gem "jeweler"
@@ -17,4 +17,5 @@ group :development do
   gem 'yui-compressor'
   gem 'sinatra'
   gem 'rack-test'
-end
+  gem 'yard'
+end

data/{README → README.md}

@@ -9,7 +9,7 @@ Why?
 As a javascript programmer, you often need to split your code into
 multiple files. When you have 50+ different modules / libraries, you
 need some way to resolve complex dependencies and package all you need
-and nil you don't. Jsus is an utility that allows you to do just that: 
+and nil you don't. Jsus is an utility that allows you to do just that:
 package your libraries into one piece with all dependencies included.
 
 Features
@@ -21,17 +21,17 @@ Features
   headers denoting their requirements and what they provide.
 * Jsus automatically resolves dependencies, so you don't have to worry about
   order issues or anything else.
-* Jsus allows you to make "extensions". Extension is a monkey-patch you can 
+* Jsus allows you to make "extensions". Extension is a monkey-patch you can
   apply to any other library. Because sometimes you want to make project-specific
   change to a library you don't have control over and you want to be able to
   update this library without applying manual patches from their source.
-* Jsus uses [murdoc](https://github.com/markiz/murdoc) for doccu style docs 
+* Jsus uses [murdoc](https://github.com/markiz/murdoc) for doccu style docs
   generation.
 * Jsus generates special json files denoting source and resulting project
   structure which can be useful for later introspection.
 * Jsus can also generate a special js file with loader for your dependencies,
   so that you don't need to repackage everything during development cycle.
-  
+
 Examples
 ========
 
@@ -42,6 +42,12 @@ Examples
   * `jsus . Output`
   * Look at what Output directory contains
 
+Using with Rails / Sinatra / Whatever
+=====================================
+
+Jsus comes with a middleware in its backpack. See [rails example](https://github.com/jsus/jsus-rails-app)
+and [sinatra example](https://github.com/jsus/jsus-sinatra-app).
+
 Plans
 =====
 

data/TODO

@@ -1,3 +1 @@
-* Disallow circular dependencies
-* Rails integration
-* Cleanup jsus utility
+* Disallow circular dependencies (mostly done)

data/VERSION

@@ -1 +1 @@
-0.3.1
+0.3.2

data/bin/jsus

@@ -77,6 +77,11 @@ module Jsus
             Jsus.verbose = true
           end
 
+          opts.on_tail('--very-verbose', 'very verbose mode, shows pool stats beside usual verbose stuff') do
+            Jsus.verbose = true
+            options[:display_pool_stats] = true
+          end
+
           opts.on_tail('-b', '--benchmark', 'shows time spent on various stages') do
             options[:benchmark] = true
           end
@@ -192,6 +197,7 @@ module Jsus
       setup_output_directory
       preload_pool
       load_package
+      display_pool_stats if options[:display_pool_stats]
       compile_package
       post_process if options[:postproc]
       compress_package if options[:compress]
@@ -224,6 +230,30 @@ module Jsus
       checkpoint(:dependencies)
     end
 
+    def display_pool_stats
+      checkpoint(:pool_stats)
+      puts ""
+      puts "Pool stats:"
+      puts ""
+      puts "Main package:"
+      display_package @package
+      puts "Supplementary packages:"
+      @pool.packages.each do |package|
+        display_package package
+      end
+      puts ""
+    end
+
+    def display_package(package)
+      puts "Package: #{package.name}"
+      package.source_files.to_a.sort_by {|sf| sf.filename}.each do |sf|
+        puts "    [#{sf.relative_filename}]"
+        puts "        Provides: [#{sf.provides_names.join(", ")}]"
+        puts "        Requires: [#{sf.requires_names.join(", ")}]"
+      end
+      puts ""
+    end
+
     def compile_package
       @package_content = @package.compile(nil)
       checkpoint(:compilation)
@@ -273,15 +303,8 @@ module Jsus
       includes_root = options[:includes_root] || @output_dir
       File.open(File.join(@output_dir, "includes.js"), "w") do |f|
         c = Jsus::Container.new(*(@package.source_files.to_a + @package.linked_external_dependencies.to_a))
-        script = %{
-        (function(prefix, loader) {
-          var sources = %sources%;
-          if (!loader) loader = function(path) {
-            document.write('<scr' + 'ipt src="' + (prefix || '') + path + '"></script>');
-          }
-          for (var i = 0, j = sources.length; i < j; i++) loader(sources[i]);
-        })(window.prefix, window.loader);}.sub("%sources%", JSON.pretty_generate(c.required_files(includes_root)))
-        f.puts script
+        paths = c.required_files(includes_root)
+        f.puts Jsus::Util::CodeGenerator.generate_includes(paths)
       end
       checkpoint(:includes)
     end
@@ -354,4 +377,4 @@ module Jsus
   end
 end
 
-Jsus::CLI.run!
+Jsus::CLI.run!

data/jsus.gemspec

@@ -5,27 +5,28 @@
 
 Gem::Specification.new do |s|
   s.name = %q{jsus}
-  s.version = "0.3.1"
+  s.version = "0.3.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Abramov"]
-  s.date = %q{2011-05-19}
+  s.date = %q{2011-06-19}
   s.default_executable = %q{jsus}
   s.description = %q{Javascript packager and dependency resolver}
   s.email = %q{markizko@gmail.com}
   s.executables = ["jsus"]
   s.extra_rdoc_files = [
-    "README",
+    "README.md",
     "TODO"
   ]
   s.files = [
     ".document",
     ".rspec",
     ".travis.yml",
+    ".yardopts",
     "CHANGELOG",
     "Gemfile",
     "Manifest",
-    "README",
+    "README.md",
     "Rakefile",
     "TODO",
     "UNLICENSE",
@@ -102,6 +103,7 @@ Gem::Specification.new do |s|
     "lib/jsus/source_file.rb",
     "lib/jsus/tag.rb",
     "lib/jsus/util.rb",
+    "lib/jsus/util/code_generator.rb",
     "lib/jsus/util/documenter.rb",
     "lib/jsus/util/file_cache.rb",
     "lib/jsus/util/inflection.rb",
@@ -217,7 +219,7 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<activesupport>, [">= 0"])
       s.add_runtime_dependency(%q<json_pure>, [">= 0"])
       s.add_runtime_dependency(%q<rgl>, [">= 0"])
-      s.add_development_dependency(%q<bundler>, [">= 0"])
+      s.add_development_dependency(%q<rake>, [">= 0"])
       s.add_development_dependency(%q<rspec>, [">= 0"])
       s.add_development_dependency(%q<cucumber>, [">= 0"])
       s.add_development_dependency(%q<jeweler>, [">= 0"])
@@ -228,11 +230,12 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<yui-compressor>, [">= 0"])
       s.add_development_dependency(%q<sinatra>, [">= 0"])
       s.add_development_dependency(%q<rack-test>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
     else
       s.add_dependency(%q<activesupport>, [">= 0"])
       s.add_dependency(%q<json_pure>, [">= 0"])
       s.add_dependency(%q<rgl>, [">= 0"])
-      s.add_dependency(%q<bundler>, [">= 0"])
+      s.add_dependency(%q<rake>, [">= 0"])
       s.add_dependency(%q<rspec>, [">= 0"])
       s.add_dependency(%q<cucumber>, [">= 0"])
       s.add_dependency(%q<jeweler>, [">= 0"])
@@ -243,12 +246,13 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<yui-compressor>, [">= 0"])
       s.add_dependency(%q<sinatra>, [">= 0"])
       s.add_dependency(%q<rack-test>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
     end
   else
     s.add_dependency(%q<activesupport>, [">= 0"])
     s.add_dependency(%q<json_pure>, [">= 0"])
     s.add_dependency(%q<rgl>, [">= 0"])
-    s.add_dependency(%q<bundler>, [">= 0"])
+    s.add_dependency(%q<rake>, [">= 0"])
     s.add_dependency(%q<rspec>, [">= 0"])
     s.add_dependency(%q<cucumber>, [">= 0"])
     s.add_dependency(%q<jeweler>, [">= 0"])
@@ -259,6 +263,7 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<yui-compressor>, [">= 0"])
     s.add_dependency(%q<sinatra>, [">= 0"])
     s.add_dependency(%q<rack-test>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
   end
 end
 

data/lib/jsus.rb

@@ -11,10 +11,7 @@ require 'fileutils'
 require 'pathname'
 
 #
-# Jsus -- a library for packaging up your source files.
-#
-# For better understanding of jsus ideas start with http://github.com/Markiz/jsus-examples
-#
+# Jsus -- your better javascript packager.
 #
 module Jsus
   autoload :SourceFile, 'jsus/source_file'
@@ -26,19 +23,44 @@ module Jsus
   autoload :Util,       'jsus/util'
   autoload :Middleware, 'jsus/middleware'
 
-  # Returns whether or not jsus is in verbose mode
+  # In verbose mode jsus shows a lot of warnings like missing dependencies.
+  # Default: false
+  #
+  # @return [Boolean] jsus verbosity mode
+  # @api public
   def self.verbose?
     !!@verbose
   end
 
-  # Sets verbose mode to on. In verbose mode jsus shows a lot of warnings
-  # like missing dependencies.
+  # @see .verbose?
+  # @param [Boolean] verbose verbose verbosity mode
+  # @api public
   def self.verbose=(verbose)
     @verbose = verbose
   end
 
-  # Returns current version
+  # @return [String] Jsus version
+  # @api public
   def self.version
     @version ||= File.read(File.dirname(__FILE__) + "/../VERSION")
   end
-end
+
+
+  # Circular dependencies cannot be resolved and lead to "impossible"
+  # situations and problems, like missing source files or incorrect ordering.
+  #
+  # However, checking for cycles is quite computationally expensive, which
+  # is why you may want to disable it in production mode.
+  #
+  # @return [Boolean]
+  # @api public
+  def self.look_for_cycles?
+    @look_for_cycles == nil ? true : @look_for_cycles
+  end
+
+  # @see .look_for_cycles?
+  # @param [Boolean]
+  def self.look_for_cycles=(value)
+    @look_for_cycles = value
+  end
+end

data/lib/jsus/container.rb

@@ -4,10 +4,12 @@ module Jsus
   # from an array is the fact that container maintains topological
   # sort for the source files.
   #
+  # This class is mostly used internally.
+  #
   class Container
+    # Instantiates a container from given sources.
     #
-    # Every argument for initializer is pushed into the container.
-    #
+    # @param [SourceFile]
     def initialize(*sources)
       sources.each do |source|
         push(source)
@@ -16,7 +18,9 @@ module Jsus
 
     # Public API
 
-    # Pushes an item to container
+    # Pushes an item to the container
+    #
+    # @param [SourceFile] source pushed file
     def push(source)
       if source
         if source.kind_of?(Array) || source.kind_of?(Container)
@@ -30,7 +34,9 @@ module Jsus
     end
     alias_method :<<, :push
 
-    # Flattens the container items.
+    # Flattens the container items
+    #
+    # @return [Array]
     def flatten
       map {|item| item.respond_to?(:flatten) ? item.flatten : item }.flatten
     end
@@ -38,16 +44,25 @@ module Jsus
     # Contains the source files. Please, don't use sources directly, if you
     # depend on them to be topologically sorted. Use collection methods like
     # inject/reject/map directly on the container instead.
+    #
+    # @return [Array]
+    # @api semipublic
     def sources
       @sources ||= []
     end
     alias_method :to_a, :sources
 
+    # Sets sources to new value.
+    #
+    # @api semipublic
     def sources=(new_value) # :nodoc:
       @sources = new_value
     end
 
-    # Performs a sort and returns self.
+    # Topologically sorts items in container if required.
+    #
+    # @return [self]
+    # @api semipublic
     def sort!
       unless sorted?
         remove_replaced_files!
@@ -57,13 +72,24 @@ module Jsus
       self
     end
 
-    # Returns whether collection is sorted already
+    # Returns whether container requires sorting.
+    #
+    # @return [Boolean]
+    # @api semipublic
     def sorted?
       !!@sorted
     end
 
     # Lists all the required files (dependencies and extensions) for
-    # the sources in the container.
+    # the sources in the container. Consider it a projection from source files
+    # space onto filesystem space.
+    #
+    # Optionally accepts a filesystem point to calculate relative paths from.
+    #
+    # @param [String] root point from which the relative paths are calculated.
+    #   When omitted, full paths are returned.
+    # @return [Array] ordered list of required files
+    # @api public
     def required_files(root = nil)
       sort!
       files = sources.map {|s| s.required_files }.flatten
@@ -74,13 +100,18 @@ module Jsus
       files
     end
 
-    def inspect # :nodoc:
+    # Shows inspection of the container.
+    # @api public
+    def inspect
       "#<#{self.class.name}:#{self.object_id} #{self.sources.inspect}>"
     end
 
     # Private API
 
-    def topsort # :nodoc:
+    # Performs topological sort inside current container.
+    #
+    # @api private
+    def topsort
       graph = RGL::DirectedAdjacencyGraph.new
       # init vertices
       items = sources
@@ -98,20 +129,46 @@ module Jsus
         end
       end
       result = []
+      if Jsus.look_for_cycles?
+        cycles = graph.cycles
+        unless cycles.empty?
+          puts "*" * 30
+          puts "ACHTUNG! WARNING! ATTENTION!"
+          puts "*" * 30
+          puts "Jsus has discovered you have circular dependencies in your code."
+          puts "Please resolve them immediately!"
+          puts "List of circular dependencies:"
+          cycles.each do |cycle|
+            puts "-" * 30
+            puts (cycle + [cycle.first]).map {|sf| sf.filename}.join(" => ")
+          end
+          puts "*" * 30
+        end
+      end
       graph.topsort_iterator.each { |item| result << item }
       result
     end
 
-    def dependency_cache # :nodoc:
+    # Cached map of dependencies pointing to source files.
+    # @return [Hash]
+    # @api private
+    def dependency_cache
       @dependency_cache ||= {}
     end
 
-    def provides_tree # :nodoc:
+    # Cached tree of what source files provide.
+    #
+    # @api private
+    # @return [Jsus::Util::Tree]
+    def provides_tree
       @provides_tree ||= provides_tree!
     end
 
-    # Provides tree contains
-    def provides_tree! # :nodoc:
+    # Returns tree of what source files provide.
+    #
+    # @api private
+    # @return [Jsus::Util::Tree]
+    def provides_tree!
       tree = Util::Tree.new
       # Provisions
       sources.each do |file|
@@ -128,17 +185,28 @@ module Jsus
       tree
     end
 
-    def remove_replaced_files! # :nodoc:
+    # Removes files which are marked as replaced by other sources.
+    #
+    # @api private
+    def remove_replaced_files!
       sources.reject! do |sf|
         !sf.provides.empty? && sf.provides.any? { |tag| replacements_tree[tag] && replacements_tree[tag] != sf }
       end
     end
 
-    def replacements_tree # :nodoc:
+    # Cached tree of what source files replace.
+    #
+    # @api private
+    # @return [Jsus::Util::Tree]
+    def replacements_tree
       @replacements_tree ||= replacements_tree!
     end
 
-    def replacements_tree! # :nodoc:
+    # Returns tree of what source files replace.
+    #
+    # @api private
+    # @return [Jsus::Util::Tree]
+    def replacements_tree!
       tree = Util::Tree.new
       sources.each do |file|
         if file.replaces
@@ -148,25 +216,29 @@ module Jsus
       tree
     end
 
-    def clear_cache! # :nodoc:
+    # Clears all caches for given container.
+    #
+    # @api private
+    def clear_cache!
       @provides_tree = nil
       @replacements_tree = nil
       @dependency_cache = nil
       @sorted = false
     end
 
-
+    # List of methods that clear cached state of container when called.
     CACHE_CLEAR_METHODS = [
       "map!", "reject!", "inject!", "collect!", "delete", "delete_at"
-    ] # :nodoc:
+    ]
 
+    # List of methods that are delegated to underlying array of sources.
     DELEGATED_METHODS = [
       "==", "to_a", "map", "map!", "each", "inject", "inject!",
-      "collect", "collect!", "reject", "reject!", "detect", "size", 
-      "length", "[]", "empty?", "index", "include?", "select", 
+      "collect", "collect!", "reject", "reject!", "detect", "size",
+      "length", "[]", "empty?", "index", "include?", "select",
       "delete_if", "delete", "-", "+", "|", "&"
-    ] # :nodoc:
-    # delegates most Enumerable methods to #sources
+    ]
+
     (DELEGATED_METHODS).each do |m|
       class_eval <<-EVAL
         def #{m}(*args, &block)
@@ -177,4 +249,4 @@ module Jsus
       EVAL
     end
   end
-end
+end