darkroom 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15822eea03a5814dc169523ec7285c97b12efa7e3818a5de03099b670823564d
+  data.tar.gz: 6ab19e03a8282508ea571d1d30b458750aaad273af0151d2582eeff889d69a4e
+SHA512:
+  metadata.gz: a421ab802832dd3268d8fdb17cf1c3843f5bf554ec43eace104b3e324a53bf4790f5268a65b4c1acb5b545782ab69fda5ea5aeebca62b77f3cc1ebe4889aa5d7
+  data.tar.gz: b040b997cbc321ce11af041f387bb1a89543071b9b657a38575602e8663e87573ff6442af8c016061ce29fdb67284f5301cbcbaa22b14cd8c8d1ce6a61b255db

data/LICENSE

@@ -0,0 +1,16 @@
+Copyright 2021 Nate Pickens
+
+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/README.md

@@ -0,0 +1,139 @@
+# Darkroom
+
+Darkroom is a fast, lightweight, and straightforward web asset management library. Processed assets are all
+stored in and served directly from memory rather than being written to disk (though a dump to disk can be
+performed for upload to a CDN or proxy server in production environments); this keeps asset management
+simple and performant in development. Darkroom also supports asset bundling for CSS and JavaScript using
+each language's native import statement syntax.
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem('darkroom')
+```
+
+Or install manually on the command line:
+
+```bash
+gem install darkroom
+```
+
+## Usage
+
+To create and start using a Darkroom instance, specify one or more load paths (all other arguments are
+optional):
+
+```ruby
+darkroom = Darkroom.new('app/assets', 'vendor/assets', '...',
+  hosts: ['https://cdn1.com', '...']   # Hosts to prepend to asset paths (useful in production)
+  prefix: '/static',                   # Prefix to add to all asset paths
+  pristine: ['/google-verify.html'],   # Paths with no prefix or versioning (e.g. /favicon.ico)
+  minify: true,                        # Minify assets that can be minified
+  minified_pattern: /(\.|-)min\.\w+$/, # Files that should not be minified
+  internal_pattern: /^\/components\//, # Files that cannot be accessed directly
+  min_process_interval: 1,             # Minimum time that must elapse between process calls
+)
+
+# Refreshe any assets that have been modified (in development, this should be called at the
+# beginning of each web request).
+darkroom.process
+
+# Dump assets to disk. Useful when deploying to a production environment where assets will be
+# uploaded to and served from a CDN or proxy server.
+darkroom.dump('output/dir',
+  clear: true,            # Delete contents of output/dir before dumping
+  include_pristine: true, # Include pristine assets (if preparing for CDN upload, files like
+)                         # /favicon.ico or /robots.txt should be left out)
+```
+
+Note that assets paths across all load path directories must be globally unique (e.g. the existance of both
+`app/assets/app.js` and `vendor/assets/app.js` will result in an error).
+
+To work with assets:
+
+```ruby
+# Get the external path that will be used by HTTP requests.
+path = darkroom.asset_path('/js/app.js') # => '/static/js/app-<fingerprint>.js'
+
+# Retrieve the Asset object associated with a path.
+asset = darkroom.asset(path)
+
+# Getting paths directly from an Asset object will not include any host or prefix.
+assest.path           # => '/js/app.js'
+assest.path_versioned # => '/js/app-<fingerprint>.js'
+
+asset.content_type # => 'application/javascript'
+asset.content      # Content of processed /js/app.js file
+
+asset.headers                   # => {'Content-Type' => 'application/javascript',
+                                #     'Cache-Control' => 'public, max-age=31536000'}
+asset.headers(versioned: false) # => {'Content-Type' => 'application/javascript',
+                                #     'ETag' => '<fingerprint>'}
+```
+
+## Asset Bundling
+
+CSS and JavaScript assets specify their dependencies by way of each language's native import statement. Each
+import statement is replaced with content of the referenced asset. Example:
+
+```javascript
+// Unprocessed /api.js
+function api() {
+  console.log('API called!')
+}
+
+// Unprocessed /app.js
+import '/api.js'
+
+api()
+
+// Processed /app.js
+function api() {
+  console.log('API called!')
+}
+
+
+api()
+```
+
+The same applies for CSS files. Example:
+
+```css
+/* Unprocessed /header.css */
+header {
+  background: #f1f1f1;
+}
+
+/* Unprocessed /app.css */
+@import '/header.css';
+
+body {
+  background: #fff;
+}
+
+/* Processed /app.css */
+header {
+  background: #f1f1f1;
+}
+
+
+body {
+  background: #fff;
+}
+```
+
+Imported assets can also contain import statements, and those assets are all included in the base asset.
+Imports can even be cyclical. If `asset-a.css` imports `asset-b.css` and vice-versa, each asset will simply
+contain the content of both of those assets (though order will be different as an asset's own content always
+comes after any imported assets' contents).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/npickens/darkroom.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/darkroom.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require('darkroom/asset')
+require('darkroom/darkroom')
+require('darkroom/version')
+
+require('darkroom/errors/asset_not_found_error')
+require('darkroom/errors/duplicate_asset_error')
+require('darkroom/errors/missing_library_error')
+require('darkroom/errors/processing_error')
+require('darkroom/errors/spec_not_defined_error')
+
+Darkroom::Asset.add_spec('.css', 'text/css',
+  dependency_regex: /^ *@import +(?<quote>['"]) *(?<path>.*) *\g<quote> *; *$/,
+  minify: -> (content) { CSSminify.compress(content) },
+  minify_lib: 'cssminify',
+)
+
+Darkroom::Asset.add_spec('.js', 'application/javascript',
+  dependency_regex: /^ *import +(?<quote>['"])(?<path>.*)\g<quote> *;? *$/,
+  minify: -> (content) { Uglifier.compile(content, harmony: true) },
+  minify_lib: 'uglifier',
+)
+
+Darkroom::Asset.add_spec('.htx', 'application/javascript',
+  compile: -> (path, content) { HTX.compile(path, content) },
+  compile_lib: 'htx',
+  minify: Darkroom::Asset.spec('.js').minify,
+  minify_lib: Darkroom::Asset.spec('.js').minify_lib,
+)
+
+Darkroom::Asset.add_spec('.html', '.html', 'text/html')
+Darkroom::Asset.add_spec('.ico', 'image/x-icon')
+Darkroom::Asset.add_spec('.jpg', '.jpeg', 'image/jpeg')
+Darkroom::Asset.add_spec('.png', 'image/png')
+Darkroom::Asset.add_spec('.svg', 'image/svg+xml')
+Darkroom::Asset.add_spec('.txt', 'text/plain')
+Darkroom::Asset.add_spec('.woff', 'font/woff')
+Darkroom::Asset.add_spec('.woff2', 'font/woff2')

data/lib/darkroom/asset.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require('digest')
+
+class Darkroom
+  ##
+  # Represents an asset.
+  #
+  class Asset
+    DEPENDENCY_JOINER = "\n"
+    EXTENSION_REGEX = /(?=\.\w+)/.freeze
+
+    @@specs = {}
+
+    attr_reader(:content, :error, :errors, :path, :path_versioned)
+
+    ##
+    # 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.
+    #
+    def self.extensions
+      @@specs.keys
+    end
+
+    ##
+    # 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).
+    # * +manifest+ - Manifest hash from the Darkroom instance that the asset is a member of.
+    # * +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).
+    #
+    def initialize(path, file, manifest, minify: false, internal: false)
+      @path = path
+      @file = file
+      @manifest = manifest
+      @minify = minify
+      @internal = internal
+
+      @extension = File.extname(@path).downcase
+      @spec = self.class.spec(@extension) or raise(SpecNotDefinedError.new(@extension, @file))
+
+      require_libs
+      clear
+    end
+
+    ##
+    # Processes the asset if necessary (file's mtime is compared to the last time it was processed). 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.
+    #
+    # * +key+ - Unique value associated with the current round of processing.
+    #
+    def process(key)
+      key == @process_key ? (return @modified) : (@process_key = key)
+
+      begin
+        @modified = @mtime != (@mtime = File.mtime(@file))
+        @modified ||= @dependencies.any? { |d| d.process(key) }
+
+        return false unless @modified
+      rescue Errno::ENOENT
+        clear
+        return @modified = true
+      end
+
+      clear
+      read(key)
+      compile
+      minify
+
+      @fingerprint = Digest::MD5.hexdigest(@content)
+      @path_versioned = @path.sub(EXTENSION_REGEX, "-#{@fingerprint}")
+
+      @modified
+    ensure
+      @error = @errors.empty? ? nil : ProcessingError.new(@errors)
+    end
+
+    ##
+    # Returns the HTTP MIME type string.
+    #
+    def content_type
+      @spec.content_type
+    end
+
+    ##
+    # Returns appropriate HTTP headers.
+    #
+    # * +versioned+ - Uses Cache-Control header with max-age if +true+ and ETag header if +false+.
+    #
+    def headers(versioned: true)
+      {
+        'Content-Type' => content_type,
+        'Cache-Control' => ('public, max-age=31536000' if versioned),
+        'ETag' => ("\"#{@fingerprint}\"" if !versioned),
+      }.compact!
+    end
+
+    ##
+    # Returns boolean indicating whether or not the asset is marked as internal.
+    #
+    def internal?
+      @internal
+    end
+
+    ##
+    # Returns boolean indicating whether or not an error was encountered the last time the asset was
+    # processed.
+    #
+    def error?
+      !!@error
+    end
+
+    ##
+    # Returns high-level object info string.
+    #
+    def inspect
+      "#<#{self.class}: "\
+        "@errors=#{@errors.inspect}, "\
+        "@extension=#{@extension.inspect}, "\
+        "@file=#{@file.inspect}, "\
+        "@fingerprint=#{@fingerprint.inspect}, "\
+        "@internal=#{@internal.inspect}, "\
+        "@minify=#{@minify.inspect}, "\
+        "@mtime=#{@mtime.inspect}, "\
+        "@path=#{@path.inspect}, "\
+        "@path_versioned=#{@path_versioned.inspect}"\
+      '>'
+    end
+
+    protected
+
+    ##
+    # Returns the processed content of the asset without dependencies concatenated.
+    #
+    def own_content
+      @own_content
+    end
+
+    ##
+    # Returns an array of all the asset's dependencies.
+    #
+    def dependencies
+      @dependencies
+    end
+
+    private
+
+    ##
+    # Clears content, dependencies, and errors so asset is ready for (re)processing.
+    #
+    def clear
+      (@errors ||= []).clear
+      (@dependencies ||= []).clear
+      (@content ||= +'').clear
+      (@own_content ||= +'').clear
+    end
+
+    ##
+    # Reads the asset file, building dependency array if dependencies are supported for the asset's type.
+    #
+    # * +key+ - Unique value associated with the current round of processing.
+    #
+    def read(key)
+      if @spec.dependency_regex
+        dependencies = []
+
+        File.new(@file).each.with_index do |line, line_num|
+          if (path = line[@spec.dependency_regex, :path])
+            if (dependency = @manifest[path])
+              dependencies << dependency
+            else
+              @errors << AssetNotFoundError.new(path, @path, line_num + 1)
+            end
+          else
+            @own_content << line
+          end
+        end
+
+        dependencies.each do |dependency|
+          dependency.process(key)
+
+          @dependencies += dependency.dependencies
+          @dependencies << dependency
+        end
+
+        @dependencies.uniq!
+        @dependencies.delete_if { |d| d.path == @path }
+
+        @content << @dependencies.map { |d| d.own_content }.join(DEPENDENCY_JOINER)
+        @own_content
+      else
+        @own_content = File.read(@file)
+      end
+    end
+
+    ##
+    # Compiles the asset if compilation is supported for the asset's type.
+    #
+    def compile
+      if @spec.compile
+        begin
+          @own_content = @spec.compile.call(@path, @own_content)
+        rescue => e
+          @errors << e
+        end
+      end
+
+      @content << @own_content
+    end
+
+    ##
+    # Minifies the asset if minification is supported for the asset's type, asset is marked as minifiable
+    # (i.e. it's not already minified), and the asset is not marked as internal-only.
+    #
+    def minify
+      if @spec.minify && @minify && !@internal
+        begin
+          @content = @spec.minify.call(@content)
+        rescue => e
+          @errors << e
+        end
+      end
+
+      @content
+    end
+
+    ##
+    # Requires any libraries necessary for compiling and minifying the asset based on its type. Raises a
+    # MissingLibraryError if library cannot be loaded.
+    #
+    # 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).
+    #
+    def require_libs
+      begin
+        require(@spec.compile_lib) if @spec.compile_lib
+      rescue LoadError
+        raise(MissingLibraryError.new(@spec.compile_lib, 'compile', @extension))
+      end
+
+      begin
+        require(@spec.minify_lib) if @spec.minify_lib && @minify
+      rescue LoadError
+        raise(MissingLibraryError.new(@spec.minify_lib, 'minify', @extension))
+      end
+    end
+  end
+end

data/lib/darkroom/darkroom.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require('set')
+
+##
+# Main class providing fast, lightweight, and straightforward web asset management.
+#
+class Darkroom
+  DEFAULT_INTERNAL_PATTERN = nil
+  DEFAULT_MINIFIED_PATTERN = /(\.|-)min\.\w+$/.freeze
+  PRISTINE = Set.new(%w[/favicon.ico /mask-icon.svg /humans.txt /robots.txt]).freeze
+  MIN_PROCESS_INTERVAL = 0.5
+
+  TRAILING_SLASHES = /\/+$/.freeze
+
+  attr_reader(:error, :errors)
+
+  ##
+  # Creates a new instance.
+  #
+  # * +load_paths+ - Path(s) where assets are located on disk.
+  # * +host+ - Host(s) to prepend to paths (useful when serving from a CDN in production). If multiple hosts
+  #   are specified, they will be round-robined within each thread for each call to +#asset_path+.
+  # * +hosts+ - Alias of +host+ parameter.
+  # * +prefix+ - Prefix to prepend to asset paths (e.g. +/assets+).
+  # * +pristine+ - Path(s) that should not include prefix and for which unversioned form should be provided
+  #   by default (e.g. +/favicon.ico+).
+  # * +minify+ - Boolean specifying whether or not to minify assets.
+  # * +minified_pattern+ - Regex used against asset paths to determine if they are already minified and
+  #   should therefore be skipped over for minification.
+  # * +internal_pattern+ - Regex used against asset paths to determine if they should be marked as internal
+  #   and therefore made inaccessible externally.
+  # * +min_process_interval+ - Minimum time required between one run of asset processing and another.
+  #
+  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
+
+    @hosts = (Array(host) + Array(hosts)).map! { |host| host.sub(TRAILING_SLASHES, '') }
+    @minify = minify
+    @internal_pattern = internal_pattern
+    @minified_pattern = minified_pattern
+
+    @prefix = prefix&.sub(TRAILING_SLASHES, '')
+    @prefix = nil if @prefix && @prefix.empty?
+
+    @pristine = PRISTINE.dup.merge(Array(pristine))
+
+    @min_process_interval = min_process_interval
+    @last_processed_at = 0
+    @mutex = Mutex.new
+    @manifest = {}
+
+    Thread.current[:darkroom_host_index] = -1 unless @hosts.empty?
+  end
+
+  ##
+  # Walks all load paths and refreshes any assets that have been modified on disk since the last call to
+  # this method.
+  #
+  def process
+    return if Time.now.to_f - @last_processed_at < @min_process_interval
+
+    if @mutex.locked?
+      @mutex.synchronize {}
+      return
+    end
+
+    @mutex.synchronize do
+      @errors = []
+      found = {}
+
+      @globs.each do |load_path, glob|
+        Dir.glob(glob).sort.each do |file|
+          path = file.sub(load_path, '')
+
+          if found.key?(path)
+            @errors << DuplicateAssetError.new(path, found[path], load_path)
+          else
+            found[path] = load_path
+
+            @manifest[path] ||= Asset.new(path, file, @manifest,
+              internal: internal = @internal_pattern && path =~ @internal_pattern,
+              minify: @minify && !internal && path !~ @minified_pattern,
+            )
+          end
+        end
+      end
+
+      @manifest.select! { |path, _| found.key?(path) }
+
+      found.each do |path, _|
+        @manifest[path].process(@last_processed_at)
+        @manifest[@manifest[path].path_versioned] = @manifest[path]
+
+        @errors += @manifest[path].errors
+      end
+    ensure
+      @last_processed_at = Time.now.to_f
+      @error = @errors.empty? ? nil : ProcessingError.new(@errors)
+    end
+  end
+
+  ##
+  # Does the same thing as #process, but raises an exception if any errors were encountered.
+  #
+  def process!
+    process
+
+    raise(@error) if @error
+  end
+
+  ##
+  # Returns boolean indicating whether or not there were any errors encountered the last time assets were
+  # processed.
+  #
+  def error?
+    !!@error
+  end
+
+  ##
+  # Returns an Asset object, given its external path. An external path includes any prefix and and can be
+  # either the versioned or unversioned form of the asset path (i.e. how an HTTP request for the asset comes
+  # in). For example, to get the Asset object with path +/js/app.js+ when prefix is +/assets+:
+  #
+  #   darkroom.asset('/assets/js/app.<hash>.js')
+  #   darkroom.asset('/assets/js/app.js')
+  #
+  # * +path+ - The external path of the asset.
+  #
+  def asset(path)
+    asset = @manifest[@prefix ? path.sub(@prefix, '') : path]
+
+    return nil if asset.nil?
+    return nil if asset.internal?
+    return nil if @prefix && !path.start_with?(@prefix) && !@pristine.include?(asset.path)
+    return nil if @prefix && path.start_with?(@prefix) && @pristine.include?(asset.path)
+
+    asset
+  end
+
+  ##
+  # Returns the external asset path, given its internal path. An external path includes any prefix and and
+  # can be either the versioned or unversioned form of the asset path (i.e. how an HTTP request for the
+  # asset comes in). For example, to get the external path for the Asset object with path +/js/app.js+ when
+  # prefix is +/assets+:
+  #
+  #   darkroom.asset_path('/js/app.js')                   # => /assets/js/app.<hash>.js
+  #   darkroom.asset_path('/js/app.js', versioned: false) # => /assets/js/app.js
+  #
+  # * +path+ - The 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))
+    asset = @manifest[path] or return nil
+
+    host = @hosts.empty? ? '' : @hosts[
+      Thread.current[:darkroom_host_index] = (Thread.current[:darkroom_host_index] + 1) % @hosts.size
+    ]
+    prefix = @prefix unless @pristine.include?(path)
+
+    "#{host}#{prefix}#{versioned ? asset.path_versioned : path}"
+  end
+
+  ##
+  # Calls #asset_path and raises a AssetNotFoundError if the asset doesn't exist (instead of just returning
+  # nil).
+  #
+  # * +versioned+ - Boolean indicating whether the versioned or unversioned path should be returned.
+  #
+  def asset_path!(path, versioned: true)
+    asset_path(path, versioned: versioned) or raise(AssetNotFoundError.new(path))
+  end
+
+  ##
+  # Writes assets to disk. This is useful when deploying to a production environment where assets will be
+  # uploaded to and served from a CDN or proxy server.
+  #
+  # * +dir+ - Directory to write the assets to.
+  # * +clear+ - Boolean indicating whether or not the existing contents of the directory should be deleted
+  #   before performing the dump.
+  # * +include_pristine+ - Boolean indicating whether or not to include pristine assets (when dumping for
+  #   the purpose of uploading to a CDN, assets such as /robots.txt and /favicon.ico don't need to be
+  #   included).
+  #
+  def dump(dir, clear: false, include_pristine: true)
+    dir = File.expand_path(dir)
+    written = Set.new
+
+    FileUtils.mkdir_p(dir)
+    Dir.each_child(dir) { |child| FileUtils.rm_rf(File.join(dir, child)) } if clear
+
+    @manifest.each do |_, asset|
+      next if asset.internal?
+      next if written.include?(asset.path)
+      next if @pristine.include?(asset.path) && !include_pristine
+
+      external_path = asset_path(asset.path)
+      file_path = File.join(dir, external_path)
+
+      FileUtils.mkdir_p(File.dirname(file_path))
+      File.write(file_path, asset.content)
+
+      written << asset.path
+    end
+  end
+
+  ##
+  # Returns high-level object info string.
+  #
+  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}, "\
+      "@min_process_interval=#{@min_process_interval.inspect}, "\
+      "@minified_pattern=#{@minified_pattern.inspect}, "\
+      "@minify=#{@minify.inspect}, "\
+      "@prefix=#{@prefix.inspect}, "\
+      "@pristine=#{@pristine.inspect}"\
+    '>'
+  end
+end

data/lib/darkroom/errors/asset_not_found_error.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+class Darkroom
+  ##
+  # Error class used when an asset requested explicitly or specified as a dependency of another cannot be
+  # found.
+  #
+  class AssetNotFoundError < StandardError
+    attr_reader(:path, :referenced_from, :referenced_from_line)
+
+    ##
+    # Creates a new instance.
+    #
+    # * +path+ - The path of the asset that cannot be found.
+    # * +referenced_from+ - The path of the asset the not-found asset was referenced from.
+    # * +referenced_from_line+ - The line number where the not-found asset was referenced.
+    #
+    def initialize(path, referenced_from = nil, referenced_from_line = nil)
+      @path = path
+      @referenced_from = referenced_from
+      @referenced_from_line = referenced_from_line
+    end
+
+    ##
+    # Returns a string representation of the error.
+    #
+    def to_s
+      "Asset not found#{
+        " (referenced from #{@referenced_from}:#{@referenced_from_line || '?'})" if @referenced_from
+      }: #{@path}"
+    end
+  end
+end

data/lib/darkroom/errors/duplicate_asset_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class Darkroom
+  ##
+  # Error class used when an asset exists in multiple load paths.
+  #
+  class DuplicateAssetError < StandardError
+    attr_reader(:path, :first_load_path, :second_load_path)
+
+    ##
+    # Creates a new instance.
+    #
+    # * +path+ - The path of the asset that has the same path as another asset.
+    # * +first_load_path+ - The load path where the first asset with the path was found.
+    # * +second_load_path+ - The load path where the second asset with the path was found.
+    #
+    def initialize(path, first_load_path, second_load_path)
+      @path = path
+      @first_load_path = first_load_path
+      @second_load_path = second_load_path
+    end
+
+    ##
+    # Returns a string representation of the error.
+    #
+    def to_s
+      "Asset file exists in both #{@first_load_path} and #{@second_load_path}: #{@path}"
+    end
+  end
+end

data/lib/darkroom/errors/missing_library_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class Darkroom
+  ##
+  # Error class used when a needed library cannot be loaded. See Asset#require_libs.
+  #
+  class MissingLibraryError < StandardError
+    attr_reader(:library, :need, :extension)
+
+    ##
+    # Creates a new instance.
+    #
+    # * +library+ - The name of the library that's missing.
+    # * +need+ - The reason the library is needed ('compile' or 'minify').
+    # * +extension+ - The extenion of the type of asset that needs the library.
+    #
+    def initialize(library, need, extension)
+      @library = library
+      @need = need
+      @extension = extension
+    end
+
+    ##
+    # Returns a string representation of the error.
+    #
+    def to_s
+      "Cannot #{@need} #{@extension} file(s): #{@library} library not available"
+    end
+  end
+end

data/lib/darkroom/errors/processing_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Darkroom
+  ##
+  # Error class used to wrap all accumulated errors encountered during asset processing.
+  #
+  class ProcessingError < StandardError
+    ##
+    # Creates a new instance.
+    #
+    # * +errors+ - Error or array of errors.
+    #
+    def initialize(errors)
+      @errors = Array(errors)
+    end
+
+    ##
+    # Returns a string representation of the error.
+    #
+    def to_s
+      "Errors were encountered while processing assets:\n  #{@errors.map(&:to_s).join("\n  ")}"
+    end
+
+    ##
+    # Passes any missing method call on to the @errors array.
+    #
+    def method_missing(m, *args, &block)
+      @errors.send(m, *args, &block)
+    end
+  end
+end

data/lib/darkroom/errors/spec_not_defined_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class Darkroom
+  ##
+  # Error class used when a spec is not defined for a particular file extension.
+  #
+  class SpecNotDefinedError < StandardError
+    attr_reader(:extension, :file)
+
+    ##
+    # Creates a new instance.
+    #
+    # * +extension+ - Extension for which there is no spec defined.
+    # * +file+ - File path of the asset whose loading was attempted.
+    #
+    def initialize(extension, file = nil)
+      @extension = extension
+      @file = file
+    end
+
+    ##
+    # Returns a string representation of the error.
+    #
+    def to_s
+      "Spec not defined for #{@extension} files#{" (#{@file})" if @file}"
+    end
+  end
+end

data/lib/darkroom/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Darkroom
+  VERSION = '0.0.1'
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: darkroom
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nate Pickens
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.11.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.11.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+description: Darkroom provides simple web asset management complete with dependency
+  bundling based on import statements, compilation, and minification.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- VERSION
+- lib/darkroom.rb
+- lib/darkroom/asset.rb
+- lib/darkroom/darkroom.rb
+- lib/darkroom/errors/asset_not_found_error.rb
+- lib/darkroom/errors/duplicate_asset_error.rb
+- lib/darkroom/errors/missing_library_error.rb
+- lib/darkroom/errors/processing_error.rb
+- lib/darkroom/errors/spec_not_defined_error.rb
+- lib/darkroom/version.rb
+homepage: https://github.com/npickens/darkroom
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/npickens/darkroom
+  source_code_uri: https://github.com/npickens/darkroom
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.8
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: A fast, lightweight, and straightforward web asset management library.
+test_files: []