simplecov 1.0.3 → 1.1.0

data/lib/simplecov/last_run.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "fileutils"
 require "json"
+require_relative "atomic_file"
 
 module SimpleCov
   # Reads and writes coverage/.last_run.json — the previous run's coverage
@@ -18,17 +18,24 @@ module SimpleCov
         json = File.read(last_run_path)
         return nil if json.strip.empty?
 
-        JSON.parse(json, symbolize_names: true)
+        parsed = JSON.parse(json, symbolize_names: true)
+        # The maximum_coverage_drop check digs into a Hash, so anything
+        # else in a corrupt or hand-edited file counts as "no previous
+        # run" rather than crashing the at_exit hook.
+        parsed.is_a?(Hash) ? parsed : invalid_last_run
+      rescue JSON::ParserError
+        invalid_last_run
       end
 
-      # Write to a process-private temp file, then atomically rename, so a
-      # concurrent reader (e.g. another parallel-tests worker checking
-      # MaximumCoverageDrop) never sees a half-written file.
       def write(json)
-        FileUtils.mkdir_p(SimpleCov.coverage_path)
-        temp_path = "#{last_run_path}.#{Process.pid}.tmp"
-        File.open(temp_path, "w") { |f| f.puts JSON.pretty_generate(json) }
-        File.rename(temp_path, last_run_path)
+        AtomicFile.write(last_run_path, "#{JSON.pretty_generate(json)}\n")
+      end
+
+    private
+
+      def invalid_last_run
+        warn "[SimpleCov]: Warning! Parsing JSON content of .last_run.json failed, ignoring the previous run"
+        nil
       end
     end
   end

data/lib/simplecov/lines_classifier.rb

@@ -13,6 +13,16 @@ module SimpleCov
     COMMENT_LINE = /^\s*#/
     WHITESPACE_OR_COMMENT_LINE = Regexp.union(WHITESPACE_LINE, COMMENT_LINE)
 
+    # The leading `^(\s*)#` anchor is load-bearing beyond matching the marker:
+    # `classify_line` only reaches this for lines that already passed
+    # `whitespace_line?`, which is sound only while every marker is also a
+    # comment. Loosening this to match a trailing `x = 1 # :nocov:` would stop
+    # the toggle firing. `lines_classifier_spec.rb` pins the implication.
+    #
+    # The `/o` flag freezes the interpolated nocov token at this
+    # process's first classification; a `nocov_token` configured after
+    # coverage has classified a file would be silently ignored. Sound
+    # today because configuration always precedes classification.
     def self.no_cov_line
       /^(\s*)#(\s*)(:#{SimpleCov.current_nocov_token}:)/o
     end
@@ -34,21 +44,32 @@ module SimpleCov
     def classify(lines)
       lines = lines.to_a
       directive_disabled = directive_disabled_line_set(lines)
-      skipping = false
+      # The `:nocov:` skip state lives in a one-slot box owned by this
+      # call, not in an ivar, so one classifier instance can serve
+      # concurrent `classify` calls without the toggles interleaving.
+      skip_state = [false]
 
       lines.map.with_index(1) do |line, line_number|
-        skipping = !skipping if self.class.no_cov_line?(line)
-        not_relevant_line?(line, line_number, skipping, directive_disabled) ? NOT_RELEVANT : RELEVANT
+        classify_line(line, line_number, directive_disabled, skip_state)
       end
     end
 
   private
 
-    def not_relevant_line?(line, line_number, skipping, directive_disabled)
-      skipping ||
-        self.class.no_cov_line?(line) ||
-        directive_disabled.include?(line_number) ||
-        self.class.whitespace_line?(line)
+    # A `:nocov:` marker is itself a comment, so the cheap
+    # whitespace-or-comment test can gate the token match: a line of real
+    # code cannot be a marker, and no longer pays to be checked against
+    # one. That matters because this runs per line of every
+    # tracked-but-unloaded file, once in every process of a parallel run.
+    def classify_line(line, line_number, directive_disabled, skip_state)
+      if self.class.whitespace_line?(line)
+        skip_state[0] = !skip_state[0] if self.class.no_cov_line?(line)
+        NOT_RELEVANT
+      elsif skip_state[0] || directive_disabled.include?(line_number)
+        NOT_RELEVANT
+      else
+        RELEVANT
+      end
     end
 
     def directive_disabled_line_set(lines)

data/lib/simplecov/load_global_config.rb

@@ -3,8 +3,11 @@
 # `~/.simplecov` was historically resolved via a three-step fallback chain
 # (HOME, then `Etc.getpwuid.dir`, then `~$USER`) for hostile container
 # environments circa 2017. Modern CRuby/JRuby/TruffleRuby all set HOME
-# reliably, so trust it and skip silently when it isn't there.
-if ENV.fetch("HOME", nil)
+# reliably, so trust it and skip silently when it isn't there. An ENV
+# check rather than Dir.home: JRuby raises from Dir.home with HOME
+# unset, and `File.expand_path("~")` raises for a set-but-empty HOME
+# (some container/CI images), which must not break `require "simplecov"`.
+unless ENV.fetch("HOME", "").empty?
   # simplecov:disable — only fires when ~/.simplecov exists, which is
   # developer-machine-dependent (we can't rely on it for the dogfood).
   global_config_path = File.join(File.expand_path("~"), ".simplecov")

data/lib/simplecov/parallel_adapters/base.rb

@@ -55,6 +55,23 @@ module SimpleCov
         def expected_worker_count
           1
         end
+
+        # The user's explicit `SimpleCov.parallel_tests false` opt-out,
+        # which every adapter's `active?` honors before its own
+        # detection.
+        def forced_off?
+          SimpleCov.parallel_tests == false
+        end
+
+        # Shared implementation of the PARALLEL_TEST_GROUPS convention
+        # both built-in adapters follow for `expected_worker_count`.
+        # Unset, empty, non-numeric, and non-positive values all mean 1:
+        # an unparseable value must not yield 0 workers, which would end
+        # the sibling wait before it started.
+        def parallel_test_groups_count
+          count = Integer(ENV.fetch("PARALLEL_TEST_GROUPS", ""), exception: false)
+          count&.positive? ? count : 1
+        end
       end
     end
   end

data/lib/simplecov/parallel_adapters/generic.rb

@@ -23,7 +23,7 @@ module SimpleCov
     class GenericAdapter < Base
       class << self
         def active?
-          return false if SimpleCov.parallel_tests == false
+          return false if forced_off?
 
           ENV.key?("TEST_ENV_NUMBER")
         end
@@ -36,7 +36,7 @@ module SimpleCov
         end
 
         def expected_worker_count
-          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+          parallel_test_groups_count
         end
       end
     end

data/lib/simplecov/parallel_adapters/parallel_tests.rb

@@ -16,7 +16,7 @@ module SimpleCov
     class ParallelTestsAdapter < Base
       class << self
         def active?
-          return false if SimpleCov.parallel_tests == false
+          return false if forced_off?
 
           ensure_loaded
           # !! to coerce `defined?` (returns nil or "constant") to a proper bool.
@@ -50,7 +50,7 @@ module SimpleCov
         end
 
         def expected_worker_count
-          ENV["PARALLEL_TEST_GROUPS"]&.to_i || 1
+          parallel_test_groups_count
         end
 
         # Auto-require `parallel_tests` when it's installed AND the env

data/lib/simplecov/parallel_coordination.rb

@@ -77,7 +77,7 @@ module SimpleCov
       deadline = monotonic_time + parallel_wait_timeout
       tracker = {count: 0, since: monotonic_time}
       loop do
-        seen = SimpleCov::ResultMerger.read_resultset.size
+        seen = current_parallel_worker_count
         return true if seen >= expected
         return true if native_wait && resultset_count_settled?(tracker, seen)
         return false if parallel_wait_timed_out?(deadline, expected, seen)
@@ -86,6 +86,11 @@ module SimpleCov
       end
     end
 
+    def current_parallel_worker_count
+      resultset = SimpleCov::ResultMerger.read_resultset
+      SimpleCov::ResultMerger.worker_identities_for_run(resultset, SimpleCov.run_id, SimpleCov.process_start_time).size
+    end
+
     # Track whether the resultset count has held steady (and positive) for
     # `PARALLEL_RESULTS_SETTLE` seconds. `tracker` carries the last count and
     # the time it last changed across poll iterations.

data/lib/simplecov/parallel_result_merger.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  #
+  # Folds a list of resultset files into one merged coverage table across
+  # forked worker processes. Drives `SimpleCov.collate(..., processes: N)`.
+  #
+  # `ResultMerger.absorb_results` is a fold over N independent
+  # read-parse-combine steps, so it splits cleanly: each worker runs that
+  # same fold over a contiguous slice of the file list and ships the pair
+  # back over a pipe, and the parent combines the handful of per-worker
+  # pairs it gets back. Reading and parsing the shards — where a collate
+  # over a few hundred CI jobs spends most of its time — is what actually
+  # parallelises.
+  #
+  # The slices are contiguous and merged back in order, so the fold visits
+  # the resultsets in the order the serial fold visits them and the merged
+  # result is identical to `SimpleCov.collate`'s, not merely equivalent.
+  #
+  # Every failure path returns nil rather than a partial merge, so the caller
+  # can redo the fold serially: reporting coverage for a subset of the
+  # resultsets would silently understate it.
+  #
+  module ParallelResultMerger
+  module_function
+
+    #
+    # `ResultMerger.merge_and_store` across `processes` forked workers. One
+    # worker hands straight back to `ResultMerger`, so the default `collate`
+    # takes exactly the path it always has and never reaches this module's
+    # machinery at all.
+    #
+    def merge_and_store(*file_paths, processes:, ignore_timeout: false)
+      return ResultMerger.merge_and_store(*file_paths, ignore_timeout: ignore_timeout) if processes < 2
+
+      result = merge_results(*file_paths, processes: processes, ignore_timeout: ignore_timeout)
+      ResultMerger.store_result(result) if result
+      result
+    end
+
+    #
+    # `ResultMerger.merge_results` across `processes` forked workers, merging
+    # in this process instead whenever the fan-out did not produce a complete
+    # merge — a runtime that cannot fork, nothing worth splitting, or a worker
+    # that died. The result is the same either way; only the time it took to
+    # get there differs.
+    #
+    def merge_results(*file_paths, processes:, ignore_timeout: false)
+      tracked_files = Set.new
+      pair = absorb_results(file_paths, processes: processes, ignore_timeout: ignore_timeout,
+                                        tracked_files: tracked_files)
+      # A nil pair means nothing was fanned out at all, so the serial path
+      # is exactly `ResultMerger.merge_results` — delegate rather than
+      # re-implement its collector wiring.
+      return ResultMerger.merge_results(*file_paths, ignore_timeout: ignore_timeout) unless pair
+
+      command_names, coverage = pair
+      ResultMerger.create_result(command_names, coverage, tracked_files: tracked_files)
+    end
+
+    #
+    # `ResultMerger.absorb_results` across at most `processes` forked
+    # workers: same arguments, same `[command_names, coverage]` return.
+    #
+    # The tracked paths a worker's slice carried come back with its payload
+    # rather than through a collector block, since the block a serial absorb
+    # takes would be mutating a Set in the wrong process.
+    #
+    # @return [Array(Array<String>, Hash), nil] the pair
+    #   `ResultMerger.create_result` consumes, or nil when the work could not
+    #   be fanned out and the caller should merge in this process instead.
+    #
+    def absorb_results(file_paths, processes:, ignore_timeout: false, tracked_files: Set.new)
+      # One worker folds the whole list anyway, and one file is a fold of
+      # one — in both cases the fork and the round trip are pure overhead.
+      return nil if processes < 2 || file_paths.size < 2
+      # The portable feature test, and the one the rest of the ecosystem uses.
+      # CRuby leaves `fork` undefined on Windows; JRuby and TruffleRuby cannot
+      # fork on the JVM and deliberately answer false here so libraries can
+      # detect that without rescuing an exception — TruffleRuby's compatibility
+      # guide names this as the correct check. They do still define
+      # `Kernel#fork` and raise `NotImplementedError` from it, so probing that
+      # instead would answer true and send them down the fan-out.
+      return nil unless Process.respond_to?(:fork)
+
+      fan_out(chunk(file_paths, processes), ignore_timeout: ignore_timeout, tracked_files: tracked_files)
+    end
+
+    # Contiguous slices whose sizes differ by at most one, so no worker is
+    # left folding twice its share while the others idle. There are never
+    # more slices than files: asking for more processes than there are
+    # resultsets just gives one resultset per process.
+    def chunk(file_paths, processes)
+      groups = [processes, file_paths.size].min
+      base, remainder = file_paths.size.divmod(groups)
+      remaining = file_paths.dup
+
+      Array.new(groups) { |index| remaining.shift(base + (index < remainder ? 1 : 0)) }
+    end
+
+    # A `fork` that fails here raises, and is left to. `absorb_results` has
+    # already excluded the runtimes that never fork, so what remains is the OS
+    # refusing a process we expected to get — EAGAIN at RLIMIT_NPROC, ENOMEM
+    # under memory pressure. That says something is wrong with the machine
+    # rather than with the merge, and quietly absorbing it would hide it.
+    def fan_out(chunks, ignore_timeout:, tracked_files: Set.new)
+      workers = spawn_workers(chunks, ignore_timeout: ignore_timeout)
+      payloads = collect(workers)
+      return nil unless payloads
+
+      payloads.each { |(_pair, tracked)| tracked_files.merge(tracked) }
+      ResultMerger.merge_coverage(*payloads.map(&:first))
+    end
+
+    def spawn_workers(chunks, ignore_timeout:)
+      workers = [] #: Array[Hash[Symbol, untyped]]
+
+      chunks.each do |chunk|
+        workers << spawn_worker(chunk, ignore_timeout: ignore_timeout)
+      rescue StandardError
+        abandon(workers)
+        raise
+      end
+
+      workers
+    end
+
+    def abandon(workers)
+      workers.each do |worker|
+        worker[:reader].close
+        succeeded?(worker[:pid])
+      end
+    end
+
+    # `fork` itself can fail (EAGAIN under a process limit). The caller
+    # cleans up the workers it knows about, but this pipe is ours: the
+    # parent's writer end always closes, and the reader closes too when
+    # no child was spawned to feed it. Steep cannot type body locals
+    # inside an ensure, hence the ignore markers; the safe navigation
+    # keeps the cleanup well-defined when `IO.pipe` itself raised.
+    def spawn_worker(chunk, ignore_timeout:)
+      reader, writer = IO.pipe
+      pid = fork { run_in_child(reader, writer, chunk, ignore_timeout) }
+      {pid: pid, reader: reader}
+    ensure
+      # steep:ignore:start
+      writer&.close
+      reader&.close unless pid
+      # steep:ignore:end
+    end
+
+    # Everything the child does. `exit!` rather than `exit` because it must
+    # never fall through to the collating process's inherited `at_exit`
+    # handlers — SimpleCov's own report generation included.
+    def run_in_child(reader, writer, chunk, ignore_timeout)
+      reader.close
+      exit!(run_worker(chunk, writer, ignore_timeout: ignore_timeout))
+    end
+
+    # The body of a worker: merge the slice, ship it back, and report the exit
+    # status the child should terminate with. Kept free of the exit itself so
+    # it can be exercised in-process.
+    #
+    # The slice's tracked paths travel with the pair because the parent needs
+    # the union across every worker to know what nothing loaded.
+    def run_worker(chunk, writer, ignore_timeout:)
+      tracked_files = Set.new
+      pair = ResultMerger.absorb_results(chunk, ignore_timeout: ignore_timeout,
+                                         &ResultMerger::UnloadedFiles.collector(tracked_files))
+      Marshal.dump([pair, tracked_files.to_a], writer)
+      writer.close
+      0
+    rescue StandardError => e
+      warn "[SimpleCov]: parallel merge worker failed: #{e.class}: #{e.message}" if SimpleCov.print_errors
+      1
+    end
+
+    # Deserializes on a thread per worker so every pipe is drained while the
+    # workers are still writing. A payload larger than the pipe buffer would
+    # otherwise block its worker mid-write, and the parent would block
+    # reaping a worker that can never finish.
+    #
+    # Returns nil if any worker failed, so the caller can fall back to the
+    # serial fold rather than report a subset of the resultsets as the whole.
+    def collect(workers)
+      payloads = drain(workers)
+      failed = workers.count { |worker| !succeeded?(worker[:pid]) }
+      return payloads if failed.zero? && payloads.all?
+
+      warn_about_failed_workers(failed, workers.size)
+      nil
+    ensure
+      workers.each { |worker| worker[:reader].close }
+    end
+
+    def drain(workers)
+      workers.map { |worker| Thread.new { read_payload(worker[:reader]) } }.map(&:value)
+    end
+
+    def read_payload(reader)
+      # The writer is a fork of this very process and the pipe never leaves
+      # it, so this is our own data coming back through our own kernel
+      # buffer, not input. A worker that died mid-write leaves the stream
+      # truncated, which Marshal reports by raising rather than returning.
+      # RBS types `Marshal.load`'s source as `_Source`, which IO satisfies
+      # structurally but not nominally.
+      # steep:ignore:start
+      Marshal.load(reader) # rubocop:disable Security/MarshalLoad
+      # steep:ignore:end
+    rescue StandardError
+      nil
+    end
+
+    def succeeded?(pid)
+      _pid, status = Process.wait2(pid)
+      status.success?
+    rescue SystemCallError
+      # Errno::ECHILD — nothing left to reap, so there is no status to judge
+      # this worker's slice by and we have to assume it did not finish.
+      false
+    end
+
+    def warn_about_failed_workers(failed, total)
+      return unless SimpleCov.print_errors
+
+      warn "[SimpleCov]: parallel merge did not complete (#{failed} of #{total} workers failed); " \
+           "merging the resultsets in this process instead."
+    end
+  end
+end

data/lib/simplecov/report_deferral.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# The clobber-prevention backstop: an empty process stands down instead
+# of formatting over a fresher report a sibling produced. Split from
+# exit_handling.rb, which orchestrates the at_exit flow that consults
+# this. See issue #581.
+module SimpleCov
+  class << self
+    # Returns true when our process has no coverage data to contribute
+    # (after the resultset merge) and a newer report already exists on
+    # disk. Typically fires when `SimpleCov.start` ran in a parent
+    # process that shelled out to the test runner. See issue #581.
+    def defer_to_existing_report?
+      return false unless existing_report_newer_than_us?
+
+      res = result
+      empty = res.nil? || res.files.empty?
+      warn_about_deferred_report if empty
+      empty
+    end
+
+    # `.last_run.json` only exists after fully successful runs, so alone
+    # it left the backstop inert when the child run failed — the case
+    # where clobbering its report hurts most. The report stamp is
+    # touched by every formatting process regardless of exit status. The
+    # rescue covers a file vanishing mid-at_exit (`rm -rf coverage`).
+    def existing_report_newer_than_us?
+      return false unless process_start_time
+
+      [SimpleCov::LastRun.last_run_path, SimpleCov::ReportStamp.path].any? do |path|
+        File.mtime(path) > process_start_time
+      rescue SystemCallError
+        false
+      end
+    end
+
+    def warn_about_deferred_report
+      return unless print_errors
+
+      ExitCodes.print_error SimpleCov::Color.colorize(
+        "Skipping SimpleCov report — this process tracked no application code and a newer " \
+        "report already exists at #{coverage_path}. This usually means SimpleCov.start ran in a " \
+        "parent process (e.g. a Rakefile or Rails' Bundler.require) that shelled out to the test " \
+        "runner. See https://github.com/simplecov-ruby/simplecov/issues/581.",
+        :yellow
+      )
+    end
+  end
+end

data/lib/simplecov/report_stamp.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module SimpleCov
+  # Touches coverage/.report_stamp whenever a report is formatted, no
+  # matter how the run ends. The clobber-prevention backstop
+  # (`SimpleCov.defer_to_existing_report?`) needs an on-disk signal that
+  # a fresher report exists, and `.last_run.json` can't be it alone:
+  # that file is only written after fully successful runs, which left
+  # the backstop inert exactly when the child run failed and its report
+  # mattered most.
+  module ReportStamp
+    class << self
+      def path
+        File.join(SimpleCov.coverage_path, ".report_stamp")
+      end
+
+      def touch
+        FileUtils.touch(path)
+      rescue SystemCallError
+        # A read-only or vanished coverage dir must not crash reporting;
+        # the stamp only powers the deferral heuristic.
+        nil
+      end
+    end
+  end
+end

data/lib/simplecov/result.rb

@@ -15,6 +15,13 @@ module SimpleCov
 
     # Returns the original Coverage.result used for this instance of SimpleCov::Result
     attr_reader :original_result
+    # Every path the producing process was told to track, loaded or not. Carried
+    # into the resultset so a merge elsewhere can inject the ones nobody loaded
+    # without needing that process's `cover` / `track_files` config. See #1250.
+    attr_reader :tracked_files
+    # Invocation and top-level worker identities used only for parallel-result
+    # coordination. They do not change which fresh suites are merged.
+    attr_reader :run_id, :worker_id
     # Returns all files that are applicable to this result (sans filters!) as instances of
     # SimpleCov::SourceFile. Aliased as :source_files
     attr_reader :files
@@ -55,10 +62,11 @@ module SimpleCov
     # FilterConfig to opt out — useful for tests that build synthetic Results
     # and don't want the project's filters or groups applied.
     def initialize(original_result, command_name: nil, created_at: nil, not_loaded_files: Set.new,
-                   report: false, filter_config: FilterConfig.new)
+                   tracked_files: [], run_id: nil, worker_id: nil, report: false, filter_config: FilterConfig.new)
       @original_result = original_result.freeze
       @command_name = command_name
       @created_at = created_at
+      initialize_coordination_metadata(tracked_files, run_id, worker_id)
       @groups_config = filter_config.groups
       builder = SourceFileBuilder.new(original_result, not_loaded_files: not_loaded_files)
       @files = builder.call
@@ -102,7 +110,13 @@ module SimpleCov
       formatter = SimpleCov.formatter
       return nil if formatter.nil?
 
-      Formatter.instance_for(formatter).format(self)
+      formatted = Formatter.format(formatter, self)
+      # Recorded regardless of how the run ends, so a parent process's
+      # clobber-prevention backstop can tell a report was produced even
+      # when this run's checks or tests failed (unlike .last_run.json,
+      # which only successful runs write).
+      SimpleCov::ReportStamp.touch
+      formatted
     end
 
     # Defines when this result has been created. Defaults to Time.now
@@ -118,23 +132,32 @@ module SimpleCov
 
     # Returns a hash representation of this Result that can be used for marshalling it into JSON
     def to_hash
-      {
-        command_name => {
-          "coverage" => coverage,
-          "timestamp" => created_at.to_i
-        }
-      }
+      data = {"coverage" => coverage, "timestamp" => created_at.to_f} #: Hash[String, untyped]
+      data["run_id"] = run_id if run_id
+      data["worker_id"] = worker_id if worker_id
+      # Omitted when empty so a run that tracks nothing writes the shape it
+      # always has, and so the key only appears where it carries information.
+      data["tracked_files"] = tracked_files unless tracked_files.empty?
+      {command_name => data}
     end
 
     # Loads a SimpleCov::Result#to_hash dump
     def self.from_hash(hash)
       hash.map do |command_name, data|
-        new(data.fetch("coverage"), command_name: command_name, created_at: Time.at(data["timestamp"]))
+        new(data.fetch("coverage"), command_name: command_name, created_at: Time.at(data["timestamp"]),
+                                    tracked_files: data["tracked_files"] || [], run_id: data["run_id"],
+                                    worker_id: data["worker_id"])
       end
     end
 
   private
 
+    def initialize_coordination_metadata(tracked_files, run_id, worker_id)
+      @tracked_files = tracked_files.to_a
+      @run_id = run_id
+      @worker_id = worker_id
+    end
+
     def warn_about_missing_source_files(missing, input_size)
       return if missing.empty?
 
@@ -156,8 +179,15 @@ module SimpleCov
       ).warn!
     end
 
+    # A live result's criterion keys are Symbols (`:lines`, `:branches`),
+    # while entries parsed back from `.resultset.json` carry Strings, and
+    # the combiners read only String keys. Serialize with String keys so a
+    # live result merged against a stored entry contributes its counts
+    # instead of being silently dropped for every shared file.
     def coverage
-      original_result.slice(*filenames)
+      original_result.slice(*filenames).transform_values do |file_coverage|
+        file_coverage.transform_keys(&:to_s)
+      end
     end
 
     # Applies the given filter chain to `@files`, dropping each source