darkroom 0.0.9 → 0.0.10

data/lib/darkroom/asset.rb

@@ -4,6 +4,7 @@ require('base64')
 require('digest')
 require('set')
 
+require_relative('delegate')
 require_relative('errors/asset_error')
 require_relative('errors/asset_not_found_error')
 require_relative('errors/circular_reference_error')
@@ -12,9 +13,7 @@ require_relative('errors/processing_error')
 require_relative('errors/unrecognized_extension_error')
 
 class Darkroom
-  ##
   # Represents an asset.
-  #
   class Asset
     EXTENSION_REGEX = /(?=\.\w+)/.freeze
     DEFAULT_QUOTE = '\''
@@ -28,6 +27,8 @@ class Darkroom
       \k<quote>
     /x.freeze
 
+    BUILT_IN_PARSE_KINDS = [:import, :reference].freeze
+
     # First item of each set is used as default, so order is important.
     REFERENCE_FORMATS = {
       'path' => Set.new(%w[versioned unversioned]),
@@ -36,18 +37,16 @@ class Darkroom
 
     attr_reader(:errors, :path, :path_unversioned)
 
-    ##
-    # Creates a new instance.
-    #
-    # [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.
-    # [entry:] Boolean indicating whether or not the asset is an entry point (i.e. accessible externally).
-    # [minify:] Boolean specifying whether or not the asset should be minified when processed.
-    # [intermediate:] Boolean indicating whether or not the asset exists solely to provide an intermediate
-    #                 form (e.g. compiled) to another asset instance.
+    # Public: Create a new instance.
     #
+    # path          - String path this asset will be referenced by (e.g. /js/app.js).
+    # file          - String absolute path of file on disk.
+    # darkroom      - Darkroom instance that the asset is a member of.
+    # prefix:       - String prefix to apply to unversioned and versioned paths.
+    # entry:        - Boolean specifying if the asset is an entry point (i.e. accessible externally).
+    # minify:       - Boolean specifying if the asset should be minified when processed.
+    # intermediate: - Boolean specifying if the asset exists solely to provide an intermediate form (e.g.
+    #                 compiled) for another Asset instance.
     def initialize(path, file, darkroom, prefix: nil, entry: true, minify: false, intermediate: false)
       @path = path
       @dir = File.dirname(path)
@@ -65,7 +64,8 @@ class Darkroom
 
       if @delegate.compile_delegate && !intermediate
         @delegate = @delegate.compile_delegate
-        @intermediate_asset = Asset.new(@path, @file, @darkroom,
+        @intermediate_asset = Asset.new(
+          @path, @file, @darkroom,
           prefix: @prefix,
           entry: false,
           minify: false,
@@ -77,12 +77,13 @@ class Darkroom
       clear
     end
 
-    ##
-    # Processes the asset if modified since the last run (see #modified? for how modification is
-    # determined). File is read from 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 and the asset is an entry point).
+    # Public: Process the asset if it's been modified since the last run (see #modified? for how
+    # modification is determined). The asset file is read from disk, references are substituted (if
+    # supported for the asset type), content is compiled (if required), imports are prefixed to the asset's
+    # own content (if supported), and content is minified (if supported and enabled and the asset is an
+    # entry point).
     #
+    # Returns nothing.
     def process
       return if ran?(:process)
 
@@ -90,97 +91,98 @@ class Darkroom
       content if entry?
     end
 
-    ##
-    # Returns the HTTP MIME type string.
+    # Public: Get the HTTP MIME type string for this asset.
     #
+    # Returns the String content type from the asset's Delegate.
     def content_type
       @delegate.content_type
     end
 
-    ##
-    # Returns boolean indicating whether or not the asset is binary.
+    # Public: Check if the asset's content is binary.
     #
+    # Returns the boolean result.
     def binary?
-      return @is_binary if defined?(@is_binary)
+      return @binary if defined?(@binary)
 
       type, subtype = content_type.split('/')
 
-      @is_binary = type != 'text' && !subtype.include?('json') && !subtype.include?('xml')
+      @binary = type != 'text' && !subtype.include?('json') && !subtype.include?('xml')
     end
 
-    ##
-    # Returns boolean indicating whether or not the asset is a font.
+    # Public: Check if the asset is a font.
     #
+    # Returns the boolean result.
     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.
+    # Public: Check if the asset is an image.
     #
+    # Returns the boolean result.
     def image?
       defined?(@is_image) ? @is_image : (@is_image = content_type.start_with?('image/'))
     end
 
-    ##
-    # Returns boolean indicating whether or not the asset is an entry point.
+    # Public: Check if the asset is an entry point.
     #
+    # Returns the boolean result.
     def entry?
       @entry
     end
 
-    ##
-    # Returns boolean indicating whether or not an error was encountered the last time the asset was
-    # processed.
+    # Public: Check if one or more errors were encountered the last time the asset was processed.
     #
+    # Returns the boolean result.
     def error?
       @errors && !@errors.empty?
     end
 
-    ##
-    # Returns ProcessingError wrapper of all errors if any exist, or nil if there are none.
+    # Public: Get a single error wrapper object for all errors.
     #
+    # Returns a ProcessingError if one or more errors exit or nil otherwise.
     def error
       @error ||= error? ? ProcessingError.new(@errors) : nil
     end
 
-    ##
-    # Returns hash of content.
+    # Public: Get an MD5 hash of the asset's content.
     #
+    # Returns the String hash.
     def fingerprint
       content
 
       @fingerprint
     end
 
-    ##
-    # Returns versioned path.
+    # Public: Get the versioned path of the asset (includes the fingerprint).
     #
+    # Returns the String versioned path.
     def path_versioned
       content
 
       @path_versioned
     end
 
-    ##
-    # Returns appropriate HTTP headers.
+    # Public: Get the asset's HTTP headers.
     #
-    # [versioned:] Uses Cache-Control header with max-age if +true+ and ETag header if +false+.
+    # versioned: - Boolean indicating if this is for the versioned or unversioned asset path. If true,
+    #              a Cache-Control header with max-age is included; if false, an ETag header is used.
     #
+    # Returns a Hash of String HTTP header names and String values.
     def headers(versioned: true)
       {
         'Content-Type' => content_type,
         'Cache-Control' => ('public, max-age=31536000' if versioned),
-        'ETag' => ("\"#{fingerprint}\"" if !versioned),
+        'ETag' => ("\"#{fingerprint}\"" unless versioned),
       }.compact!
     end
 
-    ##
-    # Returns subresource integrity string.
+    # Public: Get a subresource integrity string (SHA digest).
     #
-    # [algorithm] Hash algorithm to use to generate the integrity string (one of +:sha256+, +:sha384+, or
-    #             +:sha512+).
+    # algorithm - Symbol hash algorithm name to use to generate the integrity string (must be one of
+    #             :sha256, :sha384, :sha512).
     #
+    # Returns the String SHA digest.
+    # Raises RuntimeError if the request algorithm is not valid.
     def integrity(algorithm = :sha384)
       @integrity[algorithm] ||= "#{algorithm}-#{Base64.strict_encode64(
         case algorithm
@@ -192,11 +194,11 @@ class Darkroom
       )}".freeze
     end
 
-    ##
-    # Returns full asset content.
+    # Public: Get the full asset content, including imports and asset reference content substitutions.
     #
-    # [minified:] Boolean indicating whether or not to return minified version if it is available.
+    # minified: - Boolean specifying if the minified version is desired.
     #
+    # Returns the String asset content, minified if requested (and the asset is minifiable).
     def content(minified: @minify)
       unless ran?(:content)
         compile
@@ -221,7 +223,7 @@ class Darkroom
           )
 
           @content = finalized if finalized.kind_of?(String)
-        rescue => e
+        rescue StandardError => e
           @errors << e
         end
       end
@@ -233,7 +235,7 @@ class Darkroom
             path: @path,
             content: @content,
           )
-        rescue => e
+        rescue StandardError => e
           @errors << e
         end
       end
@@ -247,31 +249,34 @@ class Darkroom
       @content_minified.freeze
     end
 
-    ##
-    # Returns high-level object info string.
+    # Public: Get a high-level object info string about this Asset instance.
     #
+    # Returns the String.
     def inspect
-      "#<#{self.class} "\
-        "@entry=#{@entry.inspect}, "\
-        "@errors=#{@errors.inspect}, "\
-        "@extension=#{@extension.inspect}, "\
-        "@file=#{@file.inspect}, "\
-        "@fingerprint=#{@fingerprint.inspect}, "\
-        "@minify=#{@minify.inspect}, "\
-        "@mtime=#{@mtime.inspect}, "\
-        "@path=#{@path.inspect}, "\
-        "@path_unversioned=#{@path_unversioned.inspect}, "\
-        "@path_versioned=#{@path_versioned.inspect}, "\
-        "@prefix=#{@prefix.inspect}"\
+      "#<#{self.class} " \
+        "@delegate=#{@delegate.inspect}, " \
+        "@dir=#{@dir.inspect}, " \
+        "@entry=#{@entry.inspect}, " \
+        "@errors=#{@errors.inspect}, " \
+        "@extension=#{@extension.inspect}, " \
+        "@file=#{@file.inspect}, " \
+        "@fingerprint=#{@fingerprint.inspect}, " \
+        "@minify=#{@minify.inspect}, " \
+        "@modified=#{@modified.inspect}, " \
+        "@mtime=#{@mtime.inspect}, " \
+        "@path=#{@path.inspect}, " \
+        "@path_unversioned=#{@path_unversioned.inspect}, " \
+        "@path_versioned=#{@path_versioned.inspect}, " \
+        "@prefix=#{@prefix.inspect}" \
       '>'
     end
 
     protected
 
-    ##
-    # Returns true if the asset or any of its dependencies were modified since last processed, or if an
+    # Internal: Check if the asset or any of its dependencies were modified since last processed, or if an
     # error was recorded during the last processing run.
     #
+    # Returns the boolean result.
     def modified?
       @modified_key == @darkroom.process_key ? (return @modified) : @modified_key = @darkroom.process_key
 
@@ -289,9 +294,9 @@ class Darkroom
       end
     end
 
-    ##
-    # Clears content, dependencies, and errors so asset is ready for (re)processing.
+    # Internal: Clear content, dependencies, and errors so asset is ready for (re)processing.
     #
+    # Returns nothing.
     def clear
       return if ran?(:clear)
 
@@ -315,9 +320,9 @@ class Darkroom
       @errors = []
     end
 
-    ##
-    # Reads the asset file into memory.
+    # Internal: Read the asset file into memory.
     #
+    # Returns nothing.
     def read
       return if ran?(:read)
 
@@ -336,9 +341,9 @@ class Darkroom
       end
     end
 
-    ##
-    # Parses own content to build list of imports and references.
+    # Internal: Parse the asset's own content to build the lists of imports and references.
     #
+    # Returns nothing.
     def parse
       return if ran?(:parse)
 
@@ -349,7 +354,7 @@ class Darkroom
           match = Regexp.last_match
           asset = nil
 
-          if kind == :import || kind == :reference
+          if BUILT_IN_PARSE_KINDS.include?(kind)
             path = File.expand_path(match[:path], @dir)
             asset = @darkroom.manifest(path)
 
@@ -362,18 +367,18 @@ class Darkroom
       end
     end
 
-    ##
-    # Returns direct dependencies (ones explicitly specified in the asset's own content.)
+    # Internal: Get direct dependencies (ones explicitly specified in the asset's own content).
     #
+    # Returns an Array of Asset objects.
     def own_dependencies
       parse
 
       @own_dependencies
     end
 
-    ##
-    # Returns all dependencies (including dependencies of dependencies).
+    # Internal: Get all dependencies (including dependencies of dependencies).
     #
+    # Returns an Array of Asset objects.
     def dependencies
       unless ran?(:dependencies)
         parse
@@ -383,18 +388,18 @@ class Darkroom
       @dependencies
     end
 
-    ##
-    # Returns direct imports (ones explicitly specified in the asset's own content.)
+    # Internal: Get direct imports (ones explicitly specified in the asset's own content).
     #
+    # Returns an Array of Asset objects.
     def own_imports
       parse
 
       @own_imports
     end
 
-    ##
-    # Returns all imports (including imports of imports).
+    # Internal: Get all imports (including imports of imports).
     #
+    # Returns an Array of Asset objects.
     def imports
       unless ran?(:imports)
         parse
@@ -404,18 +409,18 @@ class Darkroom
       @imports
     end
 
-    ##
-    # Performs import and reference substitutions based on parse matches.
+    # Internal: Perform import and reference substitutions based on parse matches.
     #
+    # Returns nothing.
     def substitute
       return if ran?(:substitute)
 
       parse
       substitutions = []
 
-      @parse_matches.sort_by! { |_, match, __| match.begin(0) }.each do |kind, match, asset|
-        format = nil
+      @parse_matches.sort_by! { |_kind, match, _asset| match.begin(0) }
 
+      @parse_matches.each do |kind, match, asset|
         handler = @delegate.handler(kind)
         handler_args = {
           parse_data: @parse_data,
@@ -423,24 +428,29 @@ class Darkroom
         }
         handler_args[:asset] = asset if asset
 
-        if !asset && (kind == :import || kind == :reference)
-          add_parse_error(match, AssetNotFoundError)
+        if !asset && BUILT_IN_PARSE_KINDS.include?(kind)
+          add_parse_error(:not_found, match)
           next
         elsif kind == :reference
+          entity = match[:entity]
           format = match[:format]
-          format = REFERENCE_FORMATS[match[:entity]].first if format.nil? || format == ''
+
+          allowed_formats = REFERENCE_FORMATS[entity]
+          format = allowed_formats&.first if format.nil? || format == ''
 
           handler_args[:format] = format
 
           if asset.dependencies.include?(self)
-            add_parse_error(match, CircularReferenceError)
+            add_parse_error(:circular_reference, match)
+            next
+          elsif allowed_formats.nil?
+            add_parse_error(:unrecognized_reference_entity, match)
             next
-          elsif !REFERENCE_FORMATS[match[:entity]].include?(format)
-            formats = REFERENCE_FORMATS[match[:entity]].join("', '")
-            add_parse_error(match, "Invalid reference format '#{format}' (must be one of '#{formats}')")
+          elsif !allowed_formats.include?(format)
+            add_parse_error(:unrecognized_reference_format, match)
             next
-          elsif match[:entity] == 'content' && format != 'base64' && asset.binary?
-            add_parse_error(match, 'Base64 encoding is required for binary assets')
+          elsif entity == 'content' && format != 'base64' && asset.binary?
+            add_parse_error(:format_not_base64, match)
             next
           end
         end
@@ -449,10 +459,10 @@ class Darkroom
           substitution, start, finish = handler&.call(**handler_args)
 
           min_start, max_finish = match.offset(0)
-          start ||= (!format || format == 'displace') ? min_start : match.begin(:quoted)
-          finish ||= (!format || format == 'displace') ? max_finish : match.end(:quoted)
-          start = [[start, min_start].max, max_finish].min
-          finish = [[finish, max_finish].min, min_start].max
+          start ||= !format || format == 'displace' ? min_start : match.begin(:quoted)
+          finish ||= !format || format == 'displace' ? max_finish : match.end(:quoted)
+          start = start.clamp(min_start, max_finish)
+          finish = finish.clamp(min_start, max_finish)
 
           if kind == :reference
             case "#{match[:entity]}-#{format}"
@@ -477,7 +487,7 @@ class Darkroom
           nil
         end
 
-        add_parse_error(match, error) if error
+        add_parse_error(error, match) if error
       end
 
       substitutions.reverse_each do |content, start, finish|
@@ -485,9 +495,9 @@ class Darkroom
       end
     end
 
-    ##
-    # Compiles the asset if compilation is supported for the asset's type.
+    # Internal: Compile the asset if compilation is supported for the asset's type.
     #
+    # Returns nothing.
     def compile
       return if ran?(:compile)
 
@@ -501,16 +511,16 @@ class Darkroom
         )
 
         @own_content = compiled if compiled.kind_of?(String)
-      rescue => e
+      rescue StandardError => e
         @errors << e
       ensure
         @own_content.freeze
       end
     end
 
-    ##
-    # Returns the processed content of the asset without dependencies concatenated.
+    # Internal: Get the processed content of the asset without dependencies concatenated.
     #
+    # Returns the String result.
     def own_content
       compile
 
@@ -519,37 +529,35 @@ class Darkroom
 
     private
 
-    ##
-    # Requires any libraries necessary for compiling and minifying the asset based on its type. Raises a
-    # MissingLibraryError if library cannot be loaded.
+    # Internal: Require any libraries necessary for compiling, finalizing, and minifying the asset based on
+    # its type.
     #
-    # 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('terser')+ in the app's Gemfile if JavaScript minification is desired).
+    # Darkroom does not explicitly depend on any libraries necessary for asset compilation, finalization, or
+    # minification. This is because 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 libraries as direct dependencies (e.g. add
+    # gem('terser') to the app's Gemfile if JavaScript minification is desired).
     #
+    # Returns nothing.
+    # Raises MissingLibraryError if a library cannot be loaded.
     def require_libs
-      begin
-        require(@delegate.compile_lib) if @delegate.compile_lib
-      rescue LoadError
-        compile_load_error = true
-      end
+      Delegate::LIB_REQUIRES.each do |need|
+        next if need == :minify && !@minify
 
-      begin
-        require(@delegate.minify_lib) if @delegate.minify_lib && @minify
-      rescue LoadError
-        minify_load_error = true
+        begin
+          lib = @delegate.send(:"#{need}_lib")
+          require(lib) if lib
+        rescue LoadError
+          raise(MissingLibraryError.new(lib, need, @extension), cause: nil)
+        end
       end
-
-      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
 
-    ##
-    # Returns boolean indicating if a method has already been run during the current round of processing.
+    # Internal: Check if a method has already been run during the current round of processing and mark it as
+    # having been run if not.
     #
-    # [name] Name of the method.
+    # name - Symbol name of the method.
     #
+    # Returns the boolean result.
     def ran?(name)
       modified?
 
@@ -561,11 +569,11 @@ class Darkroom
       end
     end
 
-    ##
-    # Utility method used by #dependencies and #imports to recursively build arrays.
+    # Internal: Recursively build an array of Asset objects (used by #dependencies and #imports).
     #
-    # [name] Name of the array to accumulate (:dependencies or :imports).
+    # name - Symbol name of the array to accumulate (:dependencies or :imports).
     #
+    # Returns an Array of Asset objects.
     def accumulate(name)
       done = Set.new
       assets = [self]
@@ -583,28 +591,42 @@ class Darkroom
       assets
     end
 
-    ##
-    # Utility method to create a parse error of the appropriate class and append it to the errors array.
-    #
-    # [match] MatchData object for where the parse error occurred.
-    # [error] Error class or message.
-    #
-    def add_parse_error(match, error)
-      klass = error
-      args = []
-
-      if error == AssetNotFoundError
-        klass = UnrecognizedExtensionError unless Darkroom.delegate(File.extname(match[:path]))
-        args << match[:path]
+    # Internal: Create a parse error of the appropriate class and append it to the errors array.
+    #
+    # error - Symbol error type or String error message.
+    # match - MatchData object for where the parse error occurred.
+    #
+    # Returns nothing.
+    # Raises RuntimeError if error is not a String or recognized Symbol error name.
+    def add_parse_error(error, match)
+      klass = AssetError
+      args = [match[0].strip]
+
+      case error
+      when :not_found
+        path = match[:path]
+        delegate = Darkroom.delegate(File.extname(path)) if path
+        klass = delegate ? AssetNotFoundError : UnrecognizedExtensionError
+        args.clear << path
+      when :circular_reference
+        klass = CircularReferenceError
+      when :unrecognized_reference_entity
+        entity = match[:entity].nil? ? 'nil' : "'#{match[:entity]}'"
+        allowed = "'#{Asset::REFERENCE_FORMATS.keys.join("', '")}'"
+        message = "Invalid reference entity #{entity} (must be one of #{allowed})"
+      when :unrecognized_reference_format
+        entity = match[:entity]
+        format = match[:format].nil? ? 'nil' : "'#{match[:format]}'"
+        allowed = "'#{Asset::REFERENCE_FORMATS[entity].join("', '")}'"
+        message = "Invalid reference format #{format} (must be one of #{allowed})"
+      when :format_not_base64
+        message = 'Base64 encoding is required for binary assets'
       else
-        if error.kind_of?(String)
-          klass = AssetError
-          args << error
-        end
-
-        args << match[0].strip
+        message = error.to_s
       end
 
+      args.unshift(message) if message
+
       @errors << klass.new(*args, @path, @own_content[0..match.begin(:path)].count("\n") + 1)
     end
   end