darkroom 0.0.3 → 0.0.6

data/lib/darkroom/asset.rb

@@ -2,23 +2,40 @@
 
 require('base64')
 require('digest')
+require('set')
+
+require_relative('darkroom')
+require_relative('errors/asset_error')
+require_relative('errors/asset_not_found_error')
+require_relative('errors/circular_reference_error')
+require_relative('errors/missing_library_error')
+require_relative('errors/processing_error')
+require_relative('errors/unrecognized_extension_error')
 
 class Darkroom
   ##
   # Represents an asset.
   #
   class Asset
-    DEPENDENCY_JOINER = "\n"
     EXTENSION_REGEX = /(?=\.\w+)/.freeze
 
-    OPEN_QUOTE = '(?<quote>[\'"])'
-    BODY = '((?!\k<quote>).|(?<!\\\\)\\\\(\\\\\\\\)*\k<quote>)*'
-    BODY_END = '(?<!\\\\)(\\\\\\\\)*'
-    CLOSE_QUOTE = '\k<quote>'
+    IMPORT_JOINER = "\n"
+    DEFAULT_QUOTE = '\''
 
-    IMPORT_PATH_REGEX = /#{OPEN_QUOTE}(?<path>#{BODY}#{BODY_END})#{CLOSE_QUOTE}/.freeze
+    QUOTED_PATH = /(?<quote>['"])(?<path>[^'"]*)\k<quote>/.freeze
+    REFERENCE_PATH =
+      %r{
+        (?<quote>['"]?)(?<quoted>
+          (?<path>[^#{DISALLOWED_PATH_CHARS}]+)
+          \?asset-(?<entity>path|content)(=(?<format>\w*))?
+        )\k<quote>
+      }x.freeze
 
-    @@specs = {}
+    # First item of each set is used as default, so order is important.
+    REFERENCE_FORMATS = {
+      'path' => Set.new(%w[versioned unversioned]),
+      'content' => Set.new(%w[base64 utf8 displace]),
+    }.freeze
 
     attr_reader(:content, :error, :errors, :path, :path_unversioned, :path_versioned)
 
@@ -26,65 +43,45 @@ class Darkroom
     # Holds information about how to handle a particular asset type.
     #
     # * +content_type+ - HTTP MIME type string.
-    # * +dependency_regex+ - Regex to match lines of the file against to find dependencies. Must contain a
-    #   named component called 'path' (e.g. +/^import (?<path>.*)/+).
-    # * +compile+ - Proc to call that will produce the compiled version of the asset's content.
-    # * +compile_lib+ - Name of a library to +require+ that is needed by the +compile+ proc.
-    # * +minify+ - Proc to call that will produce the minified version of the asset's content.
-    # * +minify_lib+ - Name of a library to +require+ that is needed by the +minify+ proc.
-    #
-    Spec = Struct.new(:content_type, :dependency_regex, :compile, :compile_lib, :minify, :minify_lib)
-
-    ##
-    # Defines an asset spec.
-    #
-    # * +extensions+ - File extensions to associate with this spec.
-    # * +content_type+ - HTTP MIME type string.
-    # * +other+ - Optional components of the spec (see Spec struct).
-    #
-    def self.add_spec(*extensions, content_type, **other)
-      spec = Spec.new(
-        content_type.freeze,
-        other[:dependency_regex].freeze,
-        other[:compile].freeze,
-        other[:compile_lib].freeze,
-        other[:minify].freeze,
-        other[:minify_lib].freeze,
-      ).freeze
-
-      extensions.each do |extension|
-        @@specs[extension] = spec
-      end
-
-      spec
-    end
-
-    ##
-    # Returns the spec associated with a file extension.
-    #
-    # * +extension+ - File extension of the desired spec.
-    #
-    def self.spec(extension)
-      @@specs[extension]
-    end
-
-    ##
-    # Returns an array of file extensions for which specs exist.
+    # * +import_regex+ - Regex to find import statements. Must contain a named component called 'path'
+    #   (e.g. +/^import (?<path>.*)/+).
+    # * +reference_regex+ - Regex to find references to other assets. Must contain three named components:
+    #   * +path+ - Path of the asset being referenced.
+    #   * +entity+ - Desired entity (path or content).
+    #   * +format+ - Format to use (see REFERENCE_FORMATS).
+    # * +validate_reference+ - Lambda to call to validate a reference. Should return nil if there are no
+    #   errors and a string error message if validation fails. Three arguments are passed when called:
+    #   * +asset+ - Asset object of the asset being referenced.
+    #   * +match+ - MatchData object from the match against +reference_regex+.
+    #   * +format+ - Format of the reference (see REFERENCE_FORMATS).
+    # * +reference_content+ - Lambda to call to get the content for a reference. Should return nil if the
+    #   default behavior is desired or a string for custom content. Three arguments are passed when called:
+    #   * +asset+ - Asset object of the asset being referenced.
+    #   * +match+ - MatchData object from the match against +reference_regex+.
+    #   * +format+ - Format of the reference (see REFERENCE_FORMATS).
+    # * +compile_lib+ - Name of a library to +require+ that is needed by the +compile+ lambda.
+    # * +compile+ - Lambda to call that will return the compiled version of the asset's content. Two
+    #   arguments are passed when called:
+    #   * +path+ - Path of the asset being compiled.
+    #   * +content+ - Content to compile.
+    # * +minify_lib+ - Name of a library to +require+ that is needed by the +minify+ lambda.
+    # * +minify+ - Lambda to call that will return the minified version of the asset's content. One argument
+    #   is passed when called:
+    #   * +content+ - Content to minify.
     #
-    def self.extensions
-      @@specs.keys
-    end
+    Delegate = Struct.new(:content_type, :import_regex, :reference_regex, :validate_reference,
+      :reference_content, :compile_lib, :compile, :minify_lib, :minify, keyword_init: true)
 
     ##
     # Creates a new instance.
     #
-    # * +file+ - The path to the file on disk.
-    # * +path+ - The path this asset will be referenced by (e.g. /js/app.js).
+    # * +file+ - Path of file on disk.
+    # * +path+ - Path this asset will be referenced by (e.g. /js/app.js).
     # * +darkroom+ - Darkroom instance that the asset is a member of.
     # * +prefix+ - Prefix to apply to unversioned and versioned paths.
     # * +minify+ - Boolean specifying whether or not the asset should be minified when processed.
-    # * +internal+ - Boolean indicating whether or not the asset is only accessible internally (i.e. as a
-    #   dependency).
+    # * +internal+ - Boolean indicating whether or not the asset is only accessible internally (i.e. as an
+    #   import or reference).
     #
     def initialize(path, file, darkroom, prefix: nil, minify: false, internal: false)
       @path = path
@@ -96,7 +93,7 @@ class Darkroom
 
       @path_unversioned = "#{@prefix}#{@path}"
       @extension = File.extname(@path).downcase
-      @spec = self.class.spec(@extension) or raise(SpecNotDefinedError.new(@extension, @file))
+      @delegate = Darkroom.delegate(@extension) or raise(UnrecognizedExtensionError.new(@path))
 
       require_libs
       clear
@@ -104,9 +101,9 @@ class Darkroom
 
     ##
     # Processes the asset if modified (see #modified? for how modification is determined). File is read from
-    # disk, any dependencies are merged into its content (if spec for the asset type allows for it), the
-    # content is compiled (if the asset type requires compilation), and minified (if specified for this
-    # Asset). Returns true if asset was modified since it was last processed and false otherwise.
+    # disk, references are substituted (if supported), content is compiled (if required), imports are
+    # prefixed to its content (if supported), and content is minified (if supported and enabled). Returns
+    # true if asset was modified since it was last processed and false otherwise.
     #
     def process
       @process_key == @darkroom.process_key ? (return @processed) : (@process_key = @darkroom.process_key)
@@ -114,6 +111,9 @@ class Darkroom
 
       clear
       read
+      build_imports
+      build_references
+      process_dependencies
       compile
       minify
 
@@ -131,7 +131,32 @@ class Darkroom
     # Returns the HTTP MIME type string.
     #
     def content_type
-      @spec.content_type
+      @delegate.content_type
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is binary.
+    #
+    def binary?
+      return @is_binary if defined?(@is_binary)
+
+      type, subtype = content_type.split('/')
+
+      @is_binary = type != 'text' && !subtype.include?('json') && !subtype.include?('xml')
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is a font.
+    #
+    def font?
+      defined?(@is_font) ? @is_font : (@is_font = content_type.start_with?('font/'))
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is an image.
+    #
+    def image?
+      defined?(@is_image) ? @is_image : (@is_image = content_type.start_with?('image/'))
     end
 
     ##
@@ -150,8 +175,8 @@ class Darkroom
     ##
     # Returns subresource integrity string.
     #
-    # * +algorithm+ - The hash algorithm to use to generate the integrity string (one of sha256, sha384, or
-    #   sha512).
+    # * +algorithm+ - Hash algorithm to use to generate the integrity string (one of :sha256, :sha384, or
+    #   :sha512).
     #
     def integrity(algorithm = :sha384)
       @integrity[algorithm] ||= "#{algorithm}-#{Base64.strict_encode64(
@@ -219,23 +244,31 @@ class Darkroom
     ##
     # Returns all dependencies (including dependencies of dependencies).
     #
-    # * +ancestors+ - Ancestor chain followed to get to this asset as a dependency.
+    # * +ignore+ - Assets already accounted for as dependency tree is walked (to prevent infinite loops when
+    #   circular chains are encountered).
     #
-    def dependencies(ancestors = Set.new)
-      @dependencies ||= @own_dependencies.inject([]) do |dependencies, own_dependency|
-        next dependencies if ancestors.include?(self)
+    def dependencies(ignore = nil)
+      return @dependencies if @dependencies
 
-        ancestors << self
-        own_dependency.process
+      dependencies = accumulate(:dependencies, ignore)
+      @dependencies = dependencies unless ignore
 
-        dependencies |= own_dependency.dependencies(ancestors)
-        dependencies |= [own_dependency]
+      dependencies
+    end
 
-        dependencies.delete(self)
-        ancestors.delete(self)
+    ##
+    # Returns all imports (including imports of imports).
+    #
+    # * +ignore+ - Assets already accounted for as import tree is walked (to prevent infinite loops when
+    #   circular chains are encountered).
+    #
+    def imports(ignore = nil)
+      return @imports if @imports
 
-        dependencies
-      end
+      imports = accumulate(:imports, ignore)
+      @imports = imports unless ignore
+
+      imports
     end
 
     ##
@@ -252,48 +285,125 @@ class Darkroom
     #
     def clear
       @dependencies = nil
+      @imports = nil
       @error = nil
       @fingerprint = nil
       @path_versioned = nil
 
-      (@errors ||= []).clear
       (@own_dependencies ||= []).clear
+      (@own_imports ||= []).clear
+      (@dependency_matches ||= []).clear
+      (@errors ||= []).clear
       (@content ||= +'').clear
       (@own_content ||= +'').clear
       (@integrity ||= {}).clear
     end
 
     ##
-    # Reads the asset file, building dependency array if dependencies are supported for the asset's type.
+    # Reads the asset file into memory.
     #
     def read
-      unless @spec.dependency_regex
-        @own_content = File.read(@file)
-        return
-      end
+      @own_content = File.read(@file)
+    end
 
-      File.new(@file).each.with_index do |line, line_num|
-        if (path = line[@spec.dependency_regex, :path])
-          if (dependency = @darkroom.manifest(path))
-            @own_dependencies << dependency
+    ##
+    # Builds reference info.
+    #
+    def build_references
+      return unless @delegate.reference_regex
+
+      @own_content.scan(@delegate.reference_regex) do
+        match = Regexp.last_match
+        path = match[:path]
+        format = match[:format]
+        format = REFERENCE_FORMATS[match[:entity]].first if format.nil? || format == ''
+
+        if (asset = @darkroom.manifest(path))
+          if !REFERENCE_FORMATS[match[:entity]].include?(format)
+            @errors << AssetError.new("Invalid reference format '#{format}' (must be one of "\
+              "'#{REFERENCE_FORMATS[match[:entity]].join("', '")}')", match[0], @path, line_num(match))
+          elsif match[:entity] == 'content' && format != 'base64' && asset.binary?
+            @errors << AssetError.new('Base64 encoding is required for binary assets', match[0], @path,
+              line_num(match))
+          elsif (error = @delegate.validate_reference&.(asset, match, format))
+            @errors << AssetError.new(error, match[0], @path, line_num(match))
           else
-            @errors << AssetNotFoundError.new(path, @path, line_num + 1)
+            @own_dependencies << asset
+            @dependency_matches << [:reference, asset, match, format]
           end
         else
-          @own_content << line
+          @errors << not_found_error(path, match)
+        end
+      end
+    end
+
+    ##
+    # Builds import info.
+    #
+    def build_imports
+      return unless @delegate.import_regex
+
+      @own_content.scan(@delegate.import_regex) do
+        match = Regexp.last_match
+        path = match[:path]
+
+        if (asset = @darkroom.manifest(path))
+          @own_dependencies << asset
+          @own_imports << asset
+          @dependency_matches << [:import, asset, match]
+        else
+          @errors << not_found_error(path, match)
+        end
+      end
+    end
+
+    ##
+    # Processes imports and references.
+    #
+    def process_dependencies
+      @dependency_matches.sort_by! { |_, __, match| -match.begin(0) }.each do |kind, asset, match, format|
+        if kind == :import
+          @own_content[match.begin(0)...match.end(0)] = ''
+        elsif asset.dependencies.include?(self)
+          @errors << CircularReferenceError.new(match[0], @path, line_num(match))
+        else
+          value, start, finish = @delegate.reference_content&.(asset, match, format)
+          min_start, max_finish = match.offset(0)
+          start ||= format == 'displace' ? min_start : match.begin(:quoted)
+          finish ||= format == 'displace' ? max_finish : match.end(:quoted)
+          start = [[start, min_start].max, max_finish].min
+          finish = [[finish, max_finish].min, min_start].max
+
+          @own_content[start...finish] =
+            case "#{match[:entity]}-#{format}"
+            when 'path-versioned'
+              value || asset.path_versioned
+            when 'path-unversioned'
+              value || asset.path_unversioned
+            when 'content-base64'
+              quote = DEFAULT_QUOTE if match[:quote] == ''
+              data = Base64.strict_encode64(value || asset.content)
+              "#{quote}data:#{asset.content_type};base64,#{data}#{quote}"
+            when 'content-utf8'
+              quote = DEFAULT_QUOTE if match[:quote] == ''
+              "#{quote}data:#{asset.content_type};utf8,#{value || asset.content}#{quote}"
+            when 'content-displace'
+              value || asset.content
+            end
         end
       end
 
-      @content << dependencies.map { |d| d.own_content }.join(DEPENDENCY_JOINER)
+      @content << imports.map { |d| d.own_content }.join(IMPORT_JOINER)
     end
 
     ##
-    # Compiles the asset if compilation is supported for the asset's type.
+    # Compiles the asset if compilation is supported for the asset's type and appends the asset's own
+    # content to the overall content string.
     #
     def compile
-      if @spec.compile
+      if @delegate.compile
         begin
-          @own_content = @spec.compile.call(@path, @own_content)
+          @own_content = @delegate.compile.(@path, @own_content)
         rescue => e
           @errors << e
         end
@@ -307,9 +417,9 @@ class Darkroom
     # (i.e. it's not already minified), and the asset is not marked as internal-only.
     #
     def minify
-      if @spec.minify && @minify && !@internal
+      if @delegate.minify && @minify && !@internal
         begin
-          @content = @spec.minify.call(@content)
+          @content = @delegate.minify.(@content)
         rescue => e
           @errors << e
         end
@@ -325,23 +435,66 @@ class Darkroom
     # Darkroom does not explicitly depend on any libraries necessary for asset compilation or minification,
     # since not every app will use every kind of asset or use minification. It is instead up to each app
     # using Darkroom to specify any needed compilation and minification libraries as direct dependencies
-    # (e.g. specify +gem('uglifier')+ in the app's Gemfile if JavaScript minification is desired).
+    # (e.g. specify +gem('terser')+ in the app's Gemfile if JavaScript minification is desired).
     #
     def require_libs
       begin
-        require(@spec.compile_lib) if @spec.compile_lib
+        require(@delegate.compile_lib) if @delegate.compile_lib
       rescue LoadError
         compile_load_error = true
       end
 
       begin
-        require(@spec.minify_lib) if @spec.minify_lib && @minify
+        require(@delegate.minify_lib) if @delegate.minify_lib && @minify
       rescue LoadError
         minify_load_error = true
       end
 
-      raise(MissingLibraryError.new(@spec.compile_lib, 'compile', @extension)) if compile_load_error
-      raise(MissingLibraryError.new(@spec.minify_lib, 'minify', @extension)) if minify_load_error
+      raise(MissingLibraryError.new(@delegate.compile_lib, 'compile', @extension)) if compile_load_error
+      raise(MissingLibraryError.new(@delegate.minify_lib, 'minify', @extension)) if minify_load_error
+    end
+
+    ##
+    # Utility method used by #dependencies and #imports to recursively build arrays.
+    #
+    # * +name+ - Name of the array to accumulate (:dependencies or :imports).
+    # * +ignore+ - Set of assets already accumulated which can be ignored (used to avoid infinite loops when
+    #   circular references are encountered).
+    #
+    def accumulate(name, ignore)
+      ignore ||= Set.new
+      ignore << self
+
+      process
+
+      instance_variable_get(:"@own_#{name}").each_with_object([]) do |asset, assets|
+        next if ignore.include?(asset)
+
+        asset.process
+        assets.push(*asset.send(name, ignore), asset)
+        assets.uniq!
+        assets.delete(self)
+      end
+    end
+
+    ##
+    # Utility method that returns the appropriate error for a dependency that doesn't exist.
+    #
+    # * +path+ - Path of the asset which cannot be found.
+    # * +match+ - MatchData object of the regex for the asset that cannot be found.
+    #
+    def not_found_error(path, match)
+      klass = Darkroom.delegate(File.extname(path)) ? AssetNotFoundError : UnrecognizedExtensionError
+      klass.new(path, @path, line_num(match))
+    end
+
+    ##
+    # Utility method that returns the line number where a regex match was found.
+    #
+    # * +match+ - MatchData object of the regex.
+    #
+    def line_num(match)
+      @own_content[0..match.begin(:path)].count("\n") + 1
     end
   end
 end

data/lib/darkroom/darkroom.rb

@@ -2,6 +2,12 @@
 
 require('set')
 
+require_relative('asset')
+require_relative('errors/asset_not_found_error')
+require_relative('errors/duplicate_asset_error')
+require_relative('errors/invalid_path_error')
+require_relative('errors/processing_error')
+
 ##
 # Main class providing fast, lightweight, and straightforward web asset management.
 #
@@ -11,10 +17,47 @@ class Darkroom
   PRISTINE = Set.new(%w[/favicon.ico /mask-icon.svg /humans.txt /robots.txt]).freeze
   MIN_PROCESS_INTERVAL = 0.5
 
+  DISALLOWED_PATH_CHARS = '\'"`=<>? '
+  INVALID_PATH = /[#{DISALLOWED_PATH_CHARS}]/.freeze
   TRAILING_SLASHES = /\/+$/.freeze
 
+  @@delegates = {}
+  @@glob = ''
+
   attr_reader(:error, :errors, :process_key)
 
+  ##
+  # Registers an asset delegate.
+  #
+  # * +delegate+ - An HTTP MIME type string, a Hash of Delegate parameters, or a Delegate instance.
+  # * +extensions+ - File extension(s) to associate with this delegate.
+  #
+  def self.register(*extensions, delegate)
+    case delegate
+    when String
+      delegate = Asset::Delegate.new(content_type: delegate.freeze)
+    when Hash
+      delegate = Asset::Delegate.new(**delegate)
+    end
+
+    extensions.each do |extension|
+      @@delegates[extension] = delegate
+    end
+
+    @@glob = "**/*{#{@@delegates.keys.sort.join(',')}}"
+
+    delegate
+  end
+
+  ##
+  # Returns the delegate associated with a file extension.
+  #
+  # * +extension+ - File extension of the desired delegate.
+  #
+  def self.delegate(extension)
+    @@delegates[extension]
+  end
+
   ##
   # Creates a new instance.
   #
@@ -35,9 +78,7 @@ class Darkroom
   def initialize(*load_paths, host: nil, hosts: nil, prefix: nil, pristine: nil, minify: false,
       minified_pattern: DEFAULT_MINIFIED_PATTERN, internal_pattern: DEFAULT_INTERNAL_PATTERN,
       min_process_interval: MIN_PROCESS_INTERVAL)
-    @globs = load_paths.each_with_object({}) do |path, globs|
-      globs[path.chomp('/')] = File.join(path, '**', "*{#{Asset.extensions.join(',')}}")
-    end
+    @load_paths = load_paths.map { |load_path| File.expand_path(load_path) }
 
     @hosts = (Array(host) + Array(hosts)).map! { |host| host.sub(TRAILING_SLASHES, '') }
     @minify = minify
@@ -58,6 +99,8 @@ class Darkroom
     @manifest_unversioned = {}
     @manifest_versioned = {}
 
+    @errors = []
+
     Thread.current[:darkroom_host_index] = -1 unless @hosts.empty?
   end
 
@@ -75,14 +118,16 @@ class Darkroom
 
     @mutex.synchronize do
       @process_key += 1
-      @errors = []
+      @errors.clear
       found = {}
 
-      @globs.each do |load_path, glob|
-        Dir.glob(glob).sort.each do |file|
+      @load_paths.each do |load_path|
+        Dir.glob(File.join(load_path, @@glob)).sort.each do |file|
           path = file.sub(load_path, '')
 
-          if found.key?(path)
+          if index = (path =~ INVALID_PATH)
+            @errors << InvalidPathError.new(path, index)
+          elsif found.key?(path)
             @errors << DuplicateAssetError.new(path, found[path], load_path)
           else
             found[path] = load_path
@@ -141,7 +186,7 @@ class Darkroom
   #   darkroom.asset('/assets/js/app.<hash>.js')
   #   darkroom.asset('/assets/js/app.js')
   #
-  # * +path+ - The external path of the asset.
+  # * +path+ - External path of the asset.
   #
   def asset(path)
     @manifest_versioned[path] || @manifest_unversioned[path]
@@ -158,7 +203,7 @@ class Darkroom
   #
   # Raises an AssetNotFoundError if the asset doesn't exist.
   #
-  # * +path+ - The internal path of the asset.
+  # * +path+ - Internal path of the asset.
   # * +versioned+ - Boolean indicating whether the versioned or unversioned path should be returned.
   #
   def asset_path(path, versioned: !@pristine.include?(path))
@@ -174,8 +219,8 @@ class Darkroom
   # Returns an asset's subresource integrity string. Raises an AssetNotFoundError if the asset doesn't
   # exist.
   #
-  # * +path+ - The internal path of the asset.
-  # * +algorithm+ - The hash algorithm to use to generate the integrity string (see Asset#integrity).
+  # * +path+ - Internal path of the asset.
+  # * +algorithm+ - Hash algorithm to use to generate the integrity string (see Asset#integrity).
   #
   def asset_integrity(path, algorithm = nil)
     asset = @manifest[path] or raise(AssetNotFoundError.new(path))
@@ -186,7 +231,7 @@ class Darkroom
   ##
   # Returns the asset from the manifest hash associated with the given path.
   #
-  # * +path+ - The internal path of the asset.
+  # * +path+ - Internal path of the asset.
   #
   def manifest(path)
     @manifest[path]
@@ -204,6 +249,8 @@ class Darkroom
   #   included).
   #
   def dump(dir, clear: false, include_pristine: true)
+    require('fileutils')
+
     dir = File.expand_path(dir)
 
     FileUtils.mkdir_p(dir)
@@ -228,10 +275,10 @@ class Darkroom
   def inspect
     "#<#{self.class}: "\
       "@errors=#{@errors.inspect}, "\
-      "@globs=#{@globs.inspect}, "\
       "@hosts=#{@hosts.inspect}, "\
       "@internal_pattern=#{@internal_pattern.inspect}, "\
       "@last_processed_at=#{@last_processed_at.inspect}, "\
+      "@load_paths=#{@load_paths.inspect}, "\
       "@min_process_interval=#{@min_process_interval.inspect}, "\
       "@minified_pattern=#{@minified_pattern.inspect}, "\
       "@minify=#{@minify.inspect}, "\