fig 2.0.0.pre.alpha.11 → 2.0.0.pre.alpha.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 860a3d53c4807bf0933cfbf65e8dbfa16be7f1bc18c5899d2a2a1b79f2017c0d
-  data.tar.gz: 143f18d5d23eb8b170841bfc9958769241ab1de373c6fbe15ddbdfb2a5150edb
+  metadata.gz: 7f1364feade70b2eff4e25aec350a9cf3f39a874a2b9b05f110039ea3c16c760
+  data.tar.gz: '09924664a67b47b7f9fcb744509a661bfdc341546fde5610ce9782889fe0629b'
 SHA512:
-  metadata.gz: 19e727be17a0be0136373eb7a3b72670290c5d6a07cc05f03f5a46f66c398a7791fe256ebb0aa3375f010497f49b302d3bf7c0cf88c0a1281900c77a2b21907c
-  data.tar.gz: 5cac9612445d72cc3ea3958d9baa23a2a1d8229e33427190dd469f8f91b5a431e55d9599417caaf1a86e74c10b2fd9cc5f8fcd8ca11173b5968b3e1dd71e235f
+  metadata.gz: 18829c02bca0163f2ebc14144fc77662d202133d01906ffa6947a58959f889fb69c5cbbba09e0aafe534f4812cf28cbd27c840cc3a2253bea7658d2fb7ee1ac8
+  data.tar.gz: e062c0df9429ae9df726f40e502c6a58e8e356fe4e0f0a7c9992489fdc4edca1b4f834ba50453e949b5071649d1ca9709b43b67eceedd8053f57e01fce9e10d2

data/lib/fig/command/options/parser.rb

@@ -94,7 +94,7 @@ Standard options (represented as "[...]" above):
 
       [-l | --login]
 
-      [--log-level LEVEL] [--log-config PATH | --log-to-stdout]
+      [--log-level LEVEL] [--log-config PATH | --log-to-stdout] [--verbose]
       [--figrc PATH]      [--no-figrc] [--no-remote-figrc]
 
       [--suppress-vcs-comments-in-published-packages]

data/lib/fig/command/options.rb

@@ -79,6 +79,7 @@ class Fig::Command::Options
   attr_reader   :suppress_retrieves
   attr_reader   :update_lock_response
   attr_reader   :variable_to_get
+  attr_reader   :verbose
   attr_accessor :version_message
   attr_accessor :version_plain
 
@@ -177,6 +178,10 @@ class Fig::Command::Options
     return @suppress_warning_unused_retrieve
   end
 
+  def suppress_warning_unused_override?()
+    return @suppress_warning_unused_override
+  end
+
   private
 
   EXTRA_OPTIONS_DESCRIPTION = <<-'END_DESCRIPTION'
@@ -741,6 +746,13 @@ Running commands:
       @log_level = log_level
     end
 
+    @parser.on(
+      '--verbose',
+      'enable verbose output with timing information'
+    ) do
+      @verbose = true
+    end
+
     @update_lock_response = nil # Nil means wait, but warn.
     update_lock_responses = [:wait, :fail, :ignore]
     response_list = update_lock_responses.join(', ')
@@ -774,6 +786,13 @@ Running commands:
       @suppress_warning_unused_retrieve = true
     end
 
+    @parser.on(
+      '--suppress-warning-unused-override',
+      %q<don't complain about an override statement that isn't used>
+    ) do
+      @suppress_warning_unused_override = true
+    end
+
     return
   end
 

data/lib/fig/command.rb

@@ -22,6 +22,7 @@ require 'fig/runtime_environment'
 require 'fig/statement/configuration'
 require 'fig/update_lock'
 require 'fig/user_input_error'
+require 'fig/verbose_logging'
 require 'fig/working_directory_maintainer'
 
 module Fig; end
@@ -46,6 +47,11 @@ class Fig::Command
     Fig::Logging.initialize_pre_configuration(
       @options.log_to_stdout(), @options.log_level(),
     )
+    
+    # Enable verbose logging if requested
+    if @options.verbose
+      Fig::VerboseLogging.enable_verbose!
+    end
 
     actions = @options.actions()
     if actions.empty?
@@ -188,6 +194,15 @@ class Fig::Command
     return ! suppressed_warnings.include?('unused retrieve')
   end
 
+  def check_for_unused_overrides?()
+    return false if @options.suppress_warning_unused_override?
+
+    suppressed_warnings = @application_configuration['suppress warnings']
+    return true if not suppressed_warnings
+
+    return ! suppressed_warnings.include?('unused override')
+  end
+
   def configure()
     set_up_update_lock()
 
@@ -344,6 +359,14 @@ class Fig::Command
       }
     end
 
+    if check_for_unused_overrides?
+      Fig::AtExit.add {
+        if ! @suppress_further_error_messages
+          @environment.check_for_unused_overrides
+        end
+      }
+    end
+
     return
   end
 

data/lib/fig/include_backtrace.rb

@@ -17,6 +17,7 @@ class Fig::IncludeBacktrace
     @parent     = parent
     @descriptor = descriptor
     @overrides  = {}
+    @override_statements = {}  # map package_name -> Statement::Override
   end
 
   def add_override(statement)
@@ -34,14 +35,25 @@ class Fig::IncludeBacktrace
     end
 
     @overrides[package_name] = new_version
+    @override_statements[package_name] = statement
+    statement.added_to_environment(true)
   end
 
   # Returns a version.
   def get_override(package_name, default_version = nil)
     version = @overrides[package_name]
-    return version if version
+    if version
+      statement = @override_statements[package_name]
+      statement.referenced(true) if statement
+      return version
+    end
 
-    return @parent.get_override(package_name, default_version) if @parent
+    if @parent
+      result = @parent.get_override(package_name, default_version)
+      # If parent provided an override, it will mark its own statement as referenced
+      return result
+    end
+    
     return default_version
   end
 
@@ -73,4 +85,17 @@ class Fig::IncludeBacktrace
 
     stack << @descriptor
   end
+
+  # Collect all override statements from this backtrace level and parents
+  def collect_override_statements(statements = [])
+    if @parent
+      @parent.collect_override_statements(statements)
+    end
+
+    @override_statements.values.each do |statement|
+      statements << statement
+    end
+
+    return statements
+  end
 end

data/lib/fig/operating_system.rb

@@ -24,6 +24,7 @@ require 'fig/protocol/artifactory'
 require 'fig/repository_error'
 require 'fig/url'
 require 'fig/user_input_error'
+require 'fig/verbose_logging'
 
 module Fig; end
 
@@ -99,16 +100,20 @@ class Fig::OperatingSystem
   end
 
   def download_list(url)
-    begin
-      protocol, uri = decode_protocol url
-
-      return protocol.download_list uri
-    rescue SocketError => error
-      Fig::Logging.debug error.message
-      raise Fig::NetworkError.new "#{url}: #{error.message}"
-    rescue Errno::ETIMEDOUT => error
-      Fig::Logging.debug error.message
-      raise Fig::NetworkError.new "#{url}: #{error.message}"
+    Fig::VerboseLogging.time_operation("listing packages from #{url}") do
+      begin
+        protocol, uri = decode_protocol url
+
+        result = protocol.download_list uri
+        log_repository_operation("listed", url, "#{result.size} entries")
+        result
+      rescue SocketError => error
+        Fig::Logging.debug error.message
+        raise Fig::NetworkError.new "#{url}: #{error.message}"
+      rescue Errno::ETIMEDOUT => error
+        Fig::Logging.debug error.message
+        raise Fig::NetworkError.new "#{url}: #{error.message}"
+      end
     end
   end
 
@@ -124,15 +129,23 @@ class Fig::OperatingSystem
   # Returns whether the file was not downloaded because the file already
   # exists and is already up-to-date.
   def download(url, path, prompt_for_login)
-    protocol, uri = decode_protocol url
+    Fig::VerboseLogging.time_operation("downloading #{File.basename(url)}") do
+      protocol, uri = decode_protocol url
 
-    FileUtils.mkdir_p(File.dirname path)
+      FileUtils.mkdir_p(File.dirname path)
 
-    return protocol.download uri, path, prompt_for_login
+      result = protocol.download uri, path, prompt_for_login
+      if File.exist?(path)
+        size = File.size(path)
+        log_asset_operation("downloaded", path, size)
+      end
+      result
+    end
   end
 
   # Returns the basename and full path to the download.
   def download_resource(url, download_directory)
+    log_asset_operation("downloading", url)
     FileUtils.mkdir_p(download_directory)
 
     basename = CGI.unescape Fig::URL.parse(url).path.split('/').last
@@ -144,6 +157,7 @@ class Fig::OperatingSystem
   end
 
   def download_and_unpack_archive(url, download_directory, unpack_directory)
+    log_asset_operation("downloading", url)
     basename, path = download_resource(url, download_directory)
 
     case path
@@ -224,32 +238,37 @@ class Fig::OperatingSystem
   # .tgz
   # .zip
   def unpack_archive(directory, archive_path)
-    FileUtils.mkdir_p directory
-    Dir.chdir(directory) do
-      if ! File.exist? archive_path
-        raise Fig::RepositoryError.new "#{archive_path} does not exist."
-      end
-
-      running_on_windows = Fig::OperatingSystem.windows?
-      ::Archive.read_open_filename(archive_path) do |reader|
-        while entry = reader.next_header
-          if running_on_windows
-            check_archive_entry_for_windows entry, archive_path
-          end
+    Fig::VerboseLogging.time_operation("extracting archive #{File.basename(archive_path)}") do
+      FileUtils.mkdir_p directory
+      archive_size = File.size(archive_path) if File.exist?(archive_path)
+      log_asset_operation("extracting", archive_path, archive_size)
+      
+      Dir.chdir(directory) do
+        if ! File.exist? archive_path
+          raise Fig::RepositoryError.new "#{archive_path} does not exist."
+        end
 
-          begin
-            reader.extract(entry)
-          rescue Archive::Error => exception
-            # Nice how the error message doesn't include any information about
-            # what was having the problem.
-            message = exception.message.sub(/^Extract archive failed: /, '')
-            new_exception =
-              Fig::RepositoryError.new(
-                "Could not extract #{entry.pathname} from #{archive_path}: #{message}"
-              )
-
-            new_exception.set_backtrace exception.backtrace
-            raise new_exception
+        running_on_windows = Fig::OperatingSystem.windows?
+        ::Archive.read_open_filename(archive_path) do |reader|
+          while entry = reader.next_header
+            if running_on_windows
+              check_archive_entry_for_windows entry, archive_path
+            end
+
+            begin
+              reader.extract(entry)
+            rescue Archive::Error => exception
+              # Nice how the error message doesn't include any information about
+              # what was having the problem.
+              message = exception.message.sub(/^Extract archive failed: /, '')
+              new_exception =
+                Fig::RepositoryError.new(
+                  "Could not extract #{entry.pathname} from #{archive_path}: #{message}"
+                )
+
+              new_exception.set_backtrace exception.backtrace
+              raise new_exception
+            end
           end
         end
       end
@@ -363,4 +382,32 @@ class Fig::OperatingSystem
 
     return
   end
+
+  def log_repository_operation(operation, url_or_path, details = nil)
+    message = "repository #{operation}: #{url_or_path}"
+    message += " (#{details})" if details
+    Fig::VerboseLogging.verbose message
+  end
+
+  private
+
+  def log_asset_operation(operation, asset_path, size_bytes = nil)
+    message = "asset #{operation}: #{asset_path}"
+    message += " (#{format_bytes(size_bytes)})" if size_bytes
+    Fig::VerboseLogging.verbose message
+  end
+
+  def format_bytes(bytes)
+    return nil unless bytes
+    
+    if bytes < 1024
+      "#{bytes}B"
+    elsif bytes < 1024 * 1024
+      "#{(bytes / 1024.0).round(1)}KB"
+    elsif bytes < 1024 * 1024 * 1024
+      "#{(bytes / (1024.0 * 1024)).round(1)}MB"
+    else
+      "#{(bytes / (1024.0 * 1024 * 1024)).round(1)}GB"
+    end
+  end
 end

data/lib/fig/repository.rb

@@ -15,6 +15,7 @@ require 'fig/parser'
 require 'fig/repository_error'
 require 'fig/repository_package_publisher'
 require 'fig/url'
+require 'fig/verbose_logging'
 
 module Fig; end
 
@@ -79,9 +80,12 @@ class Fig::Repository
   def list_remote_packages
     check_remote_repository_format()
 
-    paths = @operating_system.download_list(remote_download_url())
-
-    return paths.reject { |path| path =~ %r< ^ #{METADATA_SUBDIRECTORY} / >xs }
+    Fig::VerboseLogging.time_operation("listing remote packages from #{remote_download_url()}") do
+      paths = @operating_system.download_list(remote_download_url())
+      filtered_paths = paths.reject { |path| path =~ %r< ^ #{METADATA_SUBDIRECTORY} / >xs }
+      Fig::VerboseLogging.verbose "found #{filtered_paths.size} packages at #{remote_download_url()}"
+      filtered_paths
+    end
   end
 
   def get_package(
@@ -296,25 +300,27 @@ class Fig::Repository
   end
 
   def update_package(descriptor)
-    temp_dir = package_download_temp_dir(descriptor)
-    begin
-      install_package(descriptor, temp_dir)
-    rescue Fig::FileNotFoundError => error
-      if @updating_package_definition
-        Fig::Logging.fatal \
-          "Package #{descriptor.to_string} not found in remote repository. (Was looking for #{error.path}.)"
-      else
-        Fig::Logging.fatal \
-          "Part of package #{descriptor.to_string} was not downloadable. (Was attempting to get #{error.path}.)"
-      end
+    Fig::VerboseLogging.time_operation("downloading package #{descriptor.to_string}") do
+      temp_dir = package_download_temp_dir(descriptor)
+      begin
+        install_package(descriptor, temp_dir)
+      rescue Fig::FileNotFoundError => error
+        if @updating_package_definition
+          Fig::Logging.fatal \
+            "Package #{descriptor.to_string} not found in remote repository. (Was looking for #{error.path}.)"
+        else
+          Fig::Logging.fatal \
+            "Part of package #{descriptor.to_string} was not downloadable. (Was attempting to get #{error.path}.)"
+        end
 
-      raise Fig::RepositoryError.new
-    rescue StandardError => exception
-      Fig::Logging.fatal %Q<Install of #{descriptor.to_string} failed: #{exception}>
+        raise Fig::RepositoryError.new
+      rescue StandardError => exception
+        Fig::Logging.fatal %Q<Install of #{descriptor.to_string} failed: #{exception}>
 
-      raise Fig::RepositoryError.new
-    ensure
-      FileUtils.rm_rf(temp_dir)
+        raise Fig::RepositoryError.new
+      ensure
+        FileUtils.rm_rf(temp_dir)
+      end
     end
 
     return
@@ -423,6 +429,7 @@ class Fig::Repository
 
   def download_assets(package, descriptor, temporary_package, temporary_runtime)
     remote_package_directory = remote_directory_for_package(descriptor)
+    
     package.archive_locations.each do
       |archive_location|
 
@@ -431,10 +438,14 @@ class Fig::Repository
           remote_package_directory, [archive_location]
         )
       end
-      @operating_system.download_and_unpack_archive(
-        archive_location, temporary_package, temporary_runtime
-      )
+      
+      Fig::VerboseLogging.time_operation("downloading and unpacking archive #{File.basename(archive_location)}") do
+        @operating_system.download_and_unpack_archive(
+          archive_location, temporary_package, temporary_runtime
+        )
+      end
     end
+    
     package.resource_locations.each do
       |resource_location|
 
@@ -444,12 +455,14 @@ class Fig::Repository
         )
       end
 
-      basename, path =
-        @operating_system.download_resource(
-          resource_location, temporary_package
-        )
+      Fig::VerboseLogging.time_operation("downloading resource #{File.basename(resource_location)}") do
+        basename, path =
+          @operating_system.download_resource(
+            resource_location, temporary_package
+          )
 
-      @operating_system.copy path, File.join(temporary_runtime, basename)
+        @operating_system.copy path, File.join(temporary_runtime, basename)
+      end
     end
 
     return

data/lib/fig/runtime_environment.rb

@@ -15,6 +15,7 @@ require 'fig/statement/override'
 require 'fig/statement/path'
 require 'fig/statement/set'
 require 'fig/user_input_error'
+require 'fig/verbose_logging'
 
 module Fig; end
 
@@ -41,6 +42,7 @@ class Fig::RuntimeEnvironment
     @retrieves                    = {}
     @named_packages               = {}
     @working_directory_maintainer = working_directory_maintainer
+    @all_override_statements      = []
   end
 
   # Returns the value of an environment variable
@@ -94,6 +96,7 @@ class Fig::RuntimeEnvironment
       return
     end
 
+    log_config_processing(package.name, package.version, config_name)
     Fig::Logging.debug(
       "Applying #{package.to_descriptive_string_with_config config_name}, package depth #{current_package_depth}."
     )
@@ -173,6 +176,7 @@ class Fig::RuntimeEnvironment
       include_file_config(package, statement, backtrace, current_package_depth)
     when Fig::Statement::Override
       backtrace.add_override(statement)
+      @all_override_statements << statement
     end
 
     return
@@ -193,6 +197,15 @@ class Fig::RuntimeEnvironment
     end
   end
 
+  def check_for_unused_overrides()
+    @all_override_statements.each do |statement|
+      if statement.loaded_but_not_referenced?
+        Fig::Logging.warn \
+          %Q<Override "#{statement.package_name}/#{statement.version}"#{statement.position_string} was never used.>
+      end
+    end
+  end
+
   private
 
   def include_config(
@@ -206,7 +219,9 @@ class Fig::RuntimeEnvironment
       include_statement.included_package.nil? && @suppress_includes == :all
 
     package, resolved_descriptor, new_backtrace =
-      determine_included_package starting_package, include_statement, backtrace
+      determine_included_package starting_package, include_statement, backtrace, current_package_depth
+
+    log_package_include(resolved_descriptor, current_package_depth)
 
     return if
           @suppress_includes == :cross_package \
@@ -225,13 +240,13 @@ class Fig::RuntimeEnvironment
       package,
       resolved_descriptor.config || Fig::Package::DEFAULT_CONFIG,
       new_backtrace,
-      next_package_depth,
+      next_package_depth
     )
 
     return
   end
 
-  def determine_included_package(starting_package, include_statement, backtrace)
+  def determine_included_package(starting_package, include_statement, backtrace, current_package_depth = 0)
     descriptor = include_statement.descriptor
 
     if ! include_statement.included_package.nil?
@@ -250,6 +265,9 @@ class Fig::RuntimeEnvironment
     )
       override = backtrace.get_override(override_package_name)
       if override
+        log_override_applied(
+          override_package_name, descriptor.version, override, current_package_depth
+        )
         resolved_descriptor =
           Fig::PackageDescriptor.new(
             override_package_name, override, descriptor.config
@@ -276,7 +294,6 @@ class Fig::RuntimeEnvironment
     including_package, include_file_statement, backtrace, current_package_depth
   )
     return if @suppress_includes.is_a? Symbol
-
     full_path = include_file_statement.full_path_relative_to including_package
 
     descriptor =
@@ -583,4 +600,40 @@ class Fig::RuntimeEnvironment
         message + ( stacktrace.empty? ? '' : "\n#{stacktrace}" )
     )
   end
+
+  private
+
+  def log_config_processing(package_name, version, config_name)
+    if package_name && !package_name.empty?
+      Fig::VerboseLogging.verbose "processing config #{config_name} for package #{package_name}/#{version || '<no version>'}"
+    else
+      Fig::VerboseLogging.verbose "processing config #{config_name} for command-line package"
+    end
+  end
+
+  def log_package_include(package_descriptor, depth)
+    # Skip logging for synthetic/unnamed packages at root level
+    if depth == 0 && package_descriptor.respond_to?(:name) && 
+       (package_descriptor.name.nil? || package_descriptor.name.empty?)
+      return
+    end
+    
+    indent = "  " * depth
+    if package_descriptor.respond_to?(:to_string)
+      descriptor_string = package_descriptor.to_string
+    elsif package_descriptor.respond_to?(:name) && package_descriptor.respond_to?(:version)
+      name = package_descriptor.name || "<unnamed>"
+      version = package_descriptor.version || "<no version>"
+      config = package_descriptor.config || "default"
+      descriptor_string = "#{name}/#{version}:#{config}"
+    else
+      descriptor_string = package_descriptor.to_s
+    end
+    Fig::VerboseLogging.verbose "#{indent}including package: #{descriptor_string}"
+  end
+
+  def log_override_applied(package_name, original_version, override_version, depth)
+    indent = "  " * depth
+    Fig::VerboseLogging.verbose "#{indent}override applied: #{package_name}/#{original_version} -> #{package_name}/#{override_version}"
+  end
 end

data/lib/fig/spec_utils.rb

@@ -18,6 +18,14 @@ require 'fig/external_program'
 require 'fig/figrc'
 require 'fig/logging'
 require 'fig/repository'
+require 'fig/verbose_logging'
+
+# Reset verbose logging state before each test to prevent test pollution
+RSpec.configure do |config|
+  config.before(:each) do
+    Fig::VerboseLogging.disable_verbose!
+  end
+end
 
 FIG_SPEC_BASE_DIRECTORY = Dir.mktmpdir 'fig-rspec-'
 at_exit { FileUtils.rm_rf FIG_SPEC_BASE_DIRECTORY }

data/lib/fig/statement/override.rb

@@ -35,6 +35,26 @@ class Fig::Statement::Override < Fig::Statement
     @version = version
   end
 
+  def loaded_but_not_referenced?()
+    return added_to_environment? && ! referenced?
+  end
+
+  def added_to_environment?()
+    return @added_to_environment
+  end
+
+  def added_to_environment(yea_or_nay)
+    @added_to_environment = yea_or_nay
+  end
+
+  def referenced?()
+    return @referenced
+  end
+
+  def referenced(yea_or_nay)
+    @referenced = yea_or_nay
+  end
+
   def statement_type()
     return 'override'
   end

data/lib/fig/verbose_logging.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+
+require 'fig/logging'
+
+module Fig; end
+
+# Core verbose logging infrastructure with timing support
+module Fig::VerboseLogging
+  @@verbose_enabled = false
+  
+  def self.enable_verbose!
+    @@verbose_enabled = true
+  end
+  
+  def self.disable_verbose!
+    @@verbose_enabled = false
+  end
+  
+  def self.verbose_enabled?
+    @@verbose_enabled
+  end
+  
+  def self.should_log_verbose?
+    @@verbose_enabled || Fig::Logging.debug?
+  end
+  
+  def self.verbose(message)
+    return unless should_log_verbose?
+    
+    if Fig::Logging.info?
+      Fig::Logging.info "[VERBOSE] #{message}"
+    else
+      # fallback to stderr if logging is completely disabled
+      $stderr.puts "[VERBOSE] #{message}" if @@verbose_enabled
+    end
+  end
+  
+  def self.time_operation(operation_name, &block)
+    return yield unless should_log_verbose?
+    
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    verbose "starting #{operation_name}"
+    
+    begin
+      result = yield
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      verbose "completed #{operation_name} in #{format_duration(duration)}"
+      result
+    rescue => error
+      duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      verbose "failed #{operation_name} after #{format_duration(duration)}: #{error.class.name}: #{error.message}"
+      raise
+    end
+  end
+  
+  def self.format_duration(seconds)
+    if seconds < 1.0
+      "#{(seconds * 1000).round(1)}ms"
+    elsif seconds < 60.0
+      "#{seconds.round(2)}s"
+    else
+      minutes = (seconds / 60).floor
+      remaining_seconds = seconds - (minutes * 60)
+      "#{minutes}m #{remaining_seconds.round(1)}s"
+    end
+  end
+end

data/lib/fig/version.rb

@@ -1,5 +1,5 @@
 # coding: utf-8
 
 module Fig
-  VERSION = '2.0.0-alpha.11'.freeze
+  VERSION = '2.0.0-alpha.12'.freeze
 end

data/spec/command/publishing_spec.rb

@@ -591,6 +591,18 @@ describe 'Fig' do
         fig(%w<--update-if-missing --include foo/1.2.3 -- hello.bat>)[0].should ==
           'cheese'
       end
+
+      it 'warns on unused override' do
+        input = <<-END
+          config default
+            override unused-package/1.0.0
+            set WHATEVER=SOMETHING
+          end
+        END
+        out, err, exit_code = fig(%w<--update-if-missing>, input)
+
+        err.should =~ /Override "unused-package\/1\.0\.0".*was never used/
+      end
     end
   end
 end

data/spec/verbose_logging_spec.rb

@@ -0,0 +1,170 @@
+# coding: utf-8
+
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+require 'fig/verbose_logging'
+require 'fig/logging'
+
+describe 'Fig::VerboseLogging' do
+  before(:each) do
+    # Reset verbose state and capture output
+    Fig::VerboseLogging.class_variable_set(:@@verbose_enabled, false)
+    @log_output = StringIO.new
+    @stderr_output = StringIO.new
+    
+    allow(Fig::Logging).to receive(:info) do |message|
+      @log_output.puts(message) if Fig::Logging.info?
+    end
+    
+    allow($stderr).to receive(:puts) do |message|
+      @stderr_output.puts(message)
+    end
+  end
+
+  describe '.time_operation' do
+    it 'logs timing when verbose is enabled' do
+      Fig::VerboseLogging.enable_verbose!
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      result = Fig::VerboseLogging.time_operation('test operation') do
+        sleep(0.01) # Small delay to ensure measurable time
+        'test result'
+      end
+      
+      expect(result).to eq('test result')
+      log_content = @log_output.string
+      expect(log_content).to include('[VERBOSE] starting test operation')
+      expect(log_content).to include('[VERBOSE] completed test operation in')
+      expect(log_content).to match(/\d+(\.\d+)?ms/)
+    end
+
+    it 'logs timing when debug logging is enabled (even without verbose flag)' do
+      allow(Fig::Logging).to receive(:debug?).and_return(true)
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      result = Fig::VerboseLogging.time_operation('test operation') do
+        'test result'
+      end
+      
+      expect(result).to eq('test result')
+      log_content = @log_output.string
+      expect(log_content).to include('[VERBOSE] starting test operation')
+    end
+
+    it 'does not log when neither verbose nor debug is enabled' do
+      allow(Fig::Logging).to receive(:debug?).and_return(false)
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      result = Fig::VerboseLogging.time_operation('test operation') do
+        'test result'
+      end
+      
+      expect(result).to eq('test result')
+      expect(@log_output.string).to be_empty
+    end
+
+    it 'falls back to stderr when logging is disabled but verbose is enabled' do
+      Fig::VerboseLogging.enable_verbose!
+      allow(Fig::Logging).to receive(:info?).and_return(false)
+      
+      result = Fig::VerboseLogging.time_operation('test operation') do
+        'test result'
+      end
+      
+      expect(result).to eq('test result')
+      stderr_content = @stderr_output.string
+      expect(stderr_content).to include('[VERBOSE] starting test operation')
+    end
+
+    it 'logs failure timing on exceptions' do
+      Fig::VerboseLogging.enable_verbose!
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      expect do
+        Fig::VerboseLogging.time_operation('failing operation') do
+          raise StandardError, 'test error'
+        end
+      end.to raise_error(StandardError, 'test error')
+      
+      log_content = @log_output.string
+      expect(log_content).to include('[VERBOSE] starting failing operation')
+      expect(log_content).to include('[VERBOSE] failed failing operation after')
+      expect(log_content).to include('StandardError: test error')
+    end
+  end
+
+  describe '.verbose' do
+    it 'logs messages when verbose is enabled' do
+      Fig::VerboseLogging.enable_verbose!
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      Fig::VerboseLogging.verbose('test message')
+      
+      log_content = @log_output.string
+      expect(log_content).to include('[VERBOSE] test message')
+    end
+
+    it 'logs messages when debug logging is enabled (even without verbose flag)' do
+      allow(Fig::Logging).to receive(:debug?).and_return(true)
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      Fig::VerboseLogging.verbose('test message')
+      
+      log_content = @log_output.string
+      expect(log_content).to include('[VERBOSE] test message')
+    end
+
+    it 'does not log when neither verbose nor debug is enabled' do
+      allow(Fig::Logging).to receive(:debug?).and_return(false)
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      Fig::VerboseLogging.verbose('test message')
+      
+      expect(@log_output.string).to be_empty
+    end
+
+    it 'falls back to stderr when logging is disabled but verbose is enabled' do
+      Fig::VerboseLogging.enable_verbose!
+      allow(Fig::Logging).to receive(:info?).and_return(false)
+      
+      Fig::VerboseLogging.verbose('test message')
+      
+      stderr_content = @stderr_output.string
+      expect(stderr_content).to include('[VERBOSE] test message')
+    end
+  end
+
+  describe '.should_log_verbose?' do
+    it 'returns true when verbose is enabled' do
+      Fig::VerboseLogging.enable_verbose!
+      expect(Fig::VerboseLogging.should_log_verbose?).to be true
+    end
+
+    it 'returns true when debug logging is enabled' do
+      allow(Fig::Logging).to receive(:debug?).and_return(true)
+      expect(Fig::VerboseLogging.should_log_verbose?).to be true
+    end
+
+    it 'returns false when neither verbose nor debug is enabled' do
+      allow(Fig::Logging).to receive(:debug?).and_return(false)
+      expect(Fig::VerboseLogging.should_log_verbose?).to be false
+    end
+  end
+
+  describe 'format helpers' do
+    it 'formats durations correctly' do
+      # Test private method via time_operation
+      Fig::VerboseLogging.enable_verbose!
+      allow(Fig::Logging).to receive(:info?).and_return(true)
+      
+      # Mock Process.clock_gettime to control duration
+      start_time = 1000.0
+      allow(Process).to receive(:clock_gettime).with(Process::CLOCK_MONOTONIC).and_return(start_time, start_time + 0.5)
+      
+      Fig::VerboseLogging.time_operation('test') { 'result' }
+      
+      log_content = @log_output.string
+      expect(log_content).to include('500.0ms') # 0.5 seconds formatted as milliseconds
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fig
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre.alpha.11
+  version: 2.0.0.pre.alpha.12
 platform: ruby
 authors:
 - Fig Folks
 bindir: bin
 cert_chain: []
-date: 2025-09-25 00:00:00.000000000 Z
+date: 2025-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bcrypt_pbkdf
@@ -334,7 +334,7 @@ dependencies:
 description: |-
   Fig is a utility for configuring environments and managing dependencies across a team of developers. Given a list of packages and a command to run, Fig builds environment variables named in those packages (e.g., CLASSPATH), then executes the command in that environment. The caller's environment is not affected.
 
-  Built from git SHA1: 23313c3-dirty
+  Built from git SHA1: f7a4d2d-dirty
 email: maintainer@figpackagemanager.org
 executables:
 - fig
@@ -501,6 +501,7 @@ files:
 - lib/fig/url.rb
 - lib/fig/url_access_disallowed_error.rb
 - lib/fig/user_input_error.rb
+- lib/fig/verbose_logging.rb
 - lib/fig/version.rb
 - lib/fig/working_directory_maintainer.rb
 - lib/fig/working_directory_metadata.rb
@@ -541,11 +542,12 @@ files:
 - spec/statement/asset_spec.rb
 - spec/statement/configuration_spec.rb
 - spec/support/formatters/seed_spitter.rb
+- spec/verbose_logging_spec.rb
 - spec/working_directory_maintainer_spec.rb
 licenses:
 - BSD-3-Clause
 metadata:
-  git_sha: 23313c3-dirty
+  git_sha: f7a4d2d-dirty
 rdoc_options: []
 require_paths:
 - lib
@@ -563,5 +565,5 @@ requirements: []
 rubygems_version: 3.6.1
 specification_version: 4
 summary: 'Utility for configuring environments and managing dependencies across a
-  team of developers. Built from git SHA1: 23313c3-dirty'
+  team of developers. Built from git SHA1: f7a4d2d-dirty'
 test_files: []