rspec-tracer 1.2.2 → 2.0.0.pre.1

data/bin/rspec-tracer

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Entry point for the `rspec-tracer` CLI. The binary is opt-in for
+# users who want diagnostics, cache inspection, or report-opening
+# from the command line; the canonical CI flow continues to go
+# through `rake rspec_tracer:remote_cache:*` tasks per
+# USER_FACING_SURFACE.md §5.
+
+lib_dir = File.expand_path('../lib', __dir__)
+$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)
+
+require 'rspec_tracer/cli'
+
+exit RSpecTracer::CLI.run(ARGV)

data/lib/rspec_tracer/cache/Rakefile

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# User-facing Rake task shim for local-cache maintenance. Load from
+# the user's own Rakefile when they want one-off cleanup:
+#
+#   spec = Gem::Specification.find_by_name('rspec-tracer')
+#   load "#{spec.gem_dir}/lib/rspec_tracer/cache/Rakefile"
+#
+# Defines `rspec_tracer:cache:gc` which prunes old run-id
+# directories under the local cache while retaining the `N`
+# most-recent configured via `cache_retention_local_count` (default
+# 5). Prune-on-save already handles the steady-state cleanup; this
+# task is for catching up after retention was opted-out-of and the
+# cache grew beyond the configured cap.
+
+require 'rspec_tracer'
+require 'rspec_tracer/storage/json_backend'
+
+namespace :rspec_tracer do
+  namespace :cache do
+    desc 'Prune old run-id directories under the local cache ' \
+         '(respects cache_retention_local_count)'
+    task :gc do
+      count = RSpecTracer.cache_retention_local_count
+      if count.nil? || count.zero?
+        RSpecTracer.logger.warn(
+          'rspec-tracer cache gc: cache_retention_local_count is 0 (opt-out); nothing to prune'
+        )
+        next
+      end
+
+      backend = RSpecTracer::Storage::JsonBackend.new(
+        cache_path: RSpecTracer.cache_path,
+        logger: RSpecTracer.logger,
+        retention_local_count: count
+      )
+      removed = backend.prune_run_dirs!(keep: count)
+      RSpecTracer.logger.info(
+        "rspec-tracer cache gc: pruned #{removed} run-id dir(s); kept #{count} most-recent"
+      )
+    end
+  end
+end

data/lib/rspec_tracer/cli/cache_clear.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer cache:clear` — remove cache, coverage, and report
+    # directories. Prompts for confirmation unless `--yes` is passed.
+    # The next rspec run is a cold run.
+    module CacheClear
+      # @param args [Array<String>] sub-command args (`-y` / `--yes`
+      #   skips confirmation; `-h` / `--help` prints help).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = success / aborted, 1 = error).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+        existing = existing_targets
+        return nothing_to_remove(stdout) if existing.empty?
+
+        announce(stdout, existing)
+        force = args.include?('--yes') || args.include?('-y')
+        return aborted(stdout) unless force || confirm?(stdout)
+
+        remove_each(stdout, existing)
+        0
+      rescue StandardError => e
+        stderr.puts "cache:clear: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.existing_targets
+        [RSpecTracer.cache_path, RSpecTracer.coverage_path, RSpecTracer.report_path]
+          .select { |path| File.directory?(path) }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.nothing_to_remove(stdout)
+        stdout.puts 'cache:clear: nothing to remove (cache directories do not exist)'
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.announce(stdout, existing)
+        stdout.puts 'cache:clear: will remove:'
+        existing.each { |path| stdout.puts "  - #{path}" }
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.confirm?(stdout)
+        stdout.print 'Proceed? [y/N] '
+        stdout.flush
+        response = $stdin.gets&.chomp&.downcase
+        %w[y yes].include?(response)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.aborted(stdout)
+        stdout.puts 'cache:clear: aborted'
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remove_each(stdout, existing)
+        existing.each do |path|
+          FileUtils.rm_rf(path)
+          stdout.puts "  removed #{path}"
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer cache:clear [--yes]
+
+          Remove cache, coverage, and report directories. The next rspec
+          run will be a cold run (full re-execution + cache rebuild).
+
+          Options:
+            -y, --yes   Skip the confirmation prompt.
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli/cache_info.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer cache:info` — show cache size, last run, and
+    # invalidation stats. Reads `last_run.json` + the run-id'd JSON
+    # files written by Storage::JsonBackend.
+    module CacheInfo
+      # @param args [Array<String>] sub-command args (`-h` / `--help`).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = success).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+
+        cache_path = RSpecTracer.cache_path
+        stdout.puts "cache_path: #{cache_path}"
+        stdout.puts "size:       #{format_bytes(directory_size(cache_path))}"
+
+        last_run_path = File.join(cache_path, 'last_run.json')
+        unless File.file?(last_run_path)
+          stdout.puts 'last_run:   no last_run.json yet (run rspec first)'
+          return 0
+        end
+
+        manifest = JSON.parse(File.read(last_run_path, encoding: 'UTF-8'))
+        run_id = manifest['run_id']
+        stdout.puts "last_run:   #{run_id}"
+        stdout.puts "generated:  #{manifest['generated_at']}" if manifest['generated_at']
+
+        print_run_summary(stdout, cache_path, run_id) if run_id
+        0
+      rescue StandardError => e
+        stderr.puts "cache:info: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer cache:info
+
+          Show the on-disk cache size, the last run id, and example counts
+          for the most recent run. Reads `last_run.json` plus the run-id'd
+          JSON files; does not modify any files.
+        HELP
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_run_summary(stdout, cache_path, run_id)
+        run_dir = File.join(cache_path, run_id)
+        return unless File.directory?(run_dir)
+
+        all_examples_path = File.join(run_dir, 'all_examples.json')
+        return unless File.file?(all_examples_path)
+
+        data = JSON.parse(File.read(all_examples_path, encoding: 'UTF-8'))
+        total = data.size
+        stdout.puts "examples:   #{total} tracked"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.directory_size(path)
+        return 0 unless File.directory?(path)
+
+        total = 0
+        Dir.glob(File.join(path, '**', '*'), File::FNM_DOTMATCH).each do |entry|
+          next unless File.file?(entry)
+
+          total += File.size(entry)
+        rescue SystemCallError
+          next
+        end
+        total
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.format_bytes(bytes)
+        return '0 B' if bytes <= 0
+
+        units = %w[B KB MB GB]
+        scale = bytes
+        unit_index = 0
+        while scale >= 1024 && unit_index < units.length - 1
+          scale /= 1024.0
+          unit_index += 1
+        end
+        format('%<scale>.1f %<unit>s', scale: scale, unit: units[unit_index])
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli/doctor.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer doctor` — diagnose config + environment.
+    # Reports Ruby + rspec-tracer versions, project root resolution,
+    # cache / coverage / report directory state, and SimpleCov / Rails
+    # presence. Exits 0 on healthy diagnosis, 1 if any check fails.
+    module Doctor
+      # @param args [Array<String>] sub-command args (`-h` / `--help`).
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = healthy, 1 = any check
+      #   FAILed; warnings keep status 0).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+
+        checks = [
+          ruby_version_check,
+          tracer_version_check,
+          project_root_check,
+          cache_path_check,
+          coverage_path_check,
+          report_path_check,
+          git_check,
+          simplecov_check,
+          rails_check,
+          cache_schema_version_check,
+          remote_cache_check,
+          ar_schema_narrow_attribution_check
+        ]
+        checks.each { |line| stdout.puts line }
+        ok = checks.none? { |line| line.start_with?('FAIL') }
+        ok ? 0 : 1
+      rescue StandardError => e
+        stderr.puts "doctor: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer doctor
+
+          Diagnose rspec-tracer config and environment. Prints a checklist
+          of versions, paths, and integrations; exits 0 if all checks pass.
+        HELP
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.ruby_version_check
+        "OK   ruby:        #{RUBY_DESCRIPTION}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.tracer_version_check
+        "OK   rspec-tracer: #{RSpecTracer::VERSION}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.project_root_check
+        "OK   root:        #{RSpecTracer.root}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.cache_path_check
+        path_check('cache_path:', RSpecTracer.cache_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.coverage_path_check
+        path_check('coverage_path:', RSpecTracer.coverage_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.report_path_check
+        path_check('report_path:', RSpecTracer.report_path)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.path_check(label, path)
+        return "FAIL #{label} <missing>" if path.nil? || path.empty?
+        return "FAIL #{label} #{path} (does not exist)" unless File.directory?(path)
+        return "FAIL #{label} #{path} (not writable)" unless File.writable?(path)
+
+        "OK   #{label} #{path}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.git_check
+        if system('git', 'rev-parse', 'HEAD', out: File::NULL, err: File::NULL)
+          'OK   git:         HEAD reachable (remote_cache will work)'
+        else
+          'WARN git:         not in a git repo (remote_cache will degrade gracefully)'
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.simplecov_check
+        if defined?(::SimpleCov)
+          'OK   SimpleCov:   loaded (interop active)'
+        else
+          'INFO SimpleCov:   not loaded (this is fine; SimpleCov is optional)'
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.rails_check
+        if defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
+          "OK   Rails:       #{::Rails::VERSION::STRING}"
+        else
+          'INFO Rails:       not loaded (this is fine for non-Rails projects)'
+        end
+      end
+
+      # Surface a 1.x->2.0 cache mismatch BEFORE the user runs
+      # rspec and watches everything re-run mysteriously. Reads the
+      # cached `last_run.json` (if any) and compares its
+      # `schema_version` against the gem's `Schema::CURRENT`. Three
+      # outcomes: no cache yet (INFO), match (OK), or mismatch (WARN
+      # with the cold-run note). Never FAIL - schema mismatches are
+      # the documented cold-run path, not a hard error.
+      def self.cache_schema_version_check
+        require 'rspec_tracer/storage/schema'
+        require 'json'
+
+        cache_path = RSpecTracer.cache_path
+        last_run_path = File.join(cache_path.to_s, 'last_run.json')
+        unless File.file?(last_run_path)
+          return 'INFO schema:      no cache yet (next rspec run is cold; expected on first install)'
+        end
+
+        manifest = JSON.parse(File.read(last_run_path, encoding: 'UTF-8'))
+        stored = manifest['schema_version']
+        current = RSpecTracer::Storage::Schema::CURRENT
+        if stored == current
+          "OK   schema:      v#{current} (matches gem)"
+        else
+          "WARN schema:      stored v#{stored.inspect} != gem v#{current} " \
+            '(next rspec run is a cold run; expected on 1.x->2.0 upgrade)'
+        end
+      rescue StandardError => e
+        "WARN schema:      could not read cache manifest: #{e.class}: #{e.message}"
+      end
+
+      # When remote_cache is configured, verify the backend is
+      # reachable from doctor's vantage point so the user catches
+      # misconfig (typo'd S3 path / unreachable Redis URL / unwritable
+      # local-fs dir) BEFORE the next CI run fails. Best-effort: never
+      # FAIL the gate, just surface a WARN/INFO line.
+      REMOTE_CACHE_PROBES = {
+        s3: ->(opts) { remote_cache_s3_check(opts) },
+        local_fs: ->(opts) { remote_cache_local_fs_check(opts) },
+        redis: ->(opts) { remote_cache_redis_check(opts) }
+      }.freeze
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_check
+        entry = remote_cache_entry
+        return 'INFO remote_cache: not configured (skip)' unless entry
+
+        backend, opts = entry
+        probe = REMOTE_CACHE_PROBES[backend]
+        return "INFO remote_cache: custom backend #{backend.inspect} (skipping reachability probe)" if probe.nil?
+
+        instance_exec(opts, &probe)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_entry
+        return nil unless RSpecTracer.respond_to?(:remote_cache_backend_entry)
+
+        RSpecTracer.remote_cache_backend_entry
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_s3_check(opts)
+        bucket = opts[:bucket] || opts['bucket']
+        return 'WARN remote_cache: :s3 configured without :bucket' if bucket.nil? || bucket.empty?
+
+        "OK   remote_cache: :s3 bucket=#{bucket} " \
+          '(reachability not probed locally; verified end-to-end on next CI run)'
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_local_fs_check(opts)
+        path = opts[:path] || opts['path']
+        return 'WARN remote_cache: :local_fs configured without :path' if path.nil? || path.empty?
+        return "WARN remote_cache: :local_fs path #{path} does not exist" unless File.directory?(path)
+        return "WARN remote_cache: :local_fs path #{path} not writable" unless File.writable?(path)
+
+        "OK   remote_cache: :local_fs path=#{path}"
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.remote_cache_redis_check(opts)
+        url = opts[:url] || opts['url'] || ENV.fetch('RSPEC_TRACER_REMOTE_CACHE_URI', nil)
+        return 'WARN remote_cache: :redis configured without :url' if url.nil? || url.empty?
+
+        "OK   remote_cache: :redis url=#{url} " \
+          '(reachability not probed locally; verified end-to-end on next CI run)'
+      end
+
+      # Surface the narrow-attribution precondition at diagnostic time.
+      # When `track_ar_schema_notifications` is enabled AND Rails is
+      # loaded AND the rspec-rails default `use_transactional_fixtures
+      # = true` is in effect, per-example BEGIN/COMMIT fires
+      # `sql.active_record` inside the rspec-tracer bucket and
+      # attribution silently widens. Same shape as the boot-time warn
+      # in RSpecTracer.start, surfaced here so users running
+      # `rspec-tracer doctor` see the issue without having to boot a
+      # full rspec run first.
+      def self.ar_schema_narrow_attribution_check
+        return 'INFO AR schema:   track_ar_schema_notifications not enabled' unless ar_schema_enabled?
+        return 'INFO AR schema:   Rails not loaded' unless rails_loaded?
+
+        if transactional_fixtures_default?
+          'WARN AR schema:   track_ar_schema_notifications + use_transactional_fixtures=true ' \
+            'silently widens to whole-suite-on-schema-change. See README ' \
+            'section "Narrow AR schema attribution".'
+        else
+          'OK   AR schema:   narrow attribution preconditions look good'
+        end
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.ar_schema_enabled?
+        return false unless RSpecTracer.respond_to?(:track_ar_schema_notifications?)
+
+        RSpecTracer.track_ar_schema_notifications?
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.rails_loaded?
+        defined?(::Rails::VERSION) && !::Rails::VERSION.nil?
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.transactional_fixtures_default?
+        return false unless defined?(::RSpec) && ::RSpec.respond_to?(:configuration)
+
+        cfg = ::RSpec.configuration
+        return false unless cfg.respond_to?(:use_transactional_fixtures)
+
+        cfg.use_transactional_fixtures != false
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/rspec_tracer/cli/explain.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RSpecTracer
+  # Internal CLI — see {RSpecTracer} for the user-facing surface.
+  # @api private
+  module CLI
+    # `rspec-tracer explain <example>` — show why a given example is
+    # scheduled to run or skip on the next rspec invocation. Reads the
+    # most recent run's JSON files (all_examples.json + dependency.json
+    # + failed_examples.json + flaky_examples.json) to surface the
+    # dependency set, last-run status, and the run-decision reason.
+    module Explain
+      # @param args [Array<String>] sub-command args. First positional
+      #   arg is the example_id (or substring) to explain.
+      # @param stdout [IO]
+      # @param stderr [IO]
+      # @return [Integer] exit status (0 = explanation printed,
+      #   1 = example not found / cache missing).
+      def self.run(args, stdout: $stdout, stderr: $stderr)
+        return print_help(stdout) if args.empty? || args.include?('-h') || args.include?('--help')
+
+        require 'rspec_tracer/load_config'
+        cache_path = RSpecTracer.cache_path
+
+        run_dir = resolve_run_dir(cache_path, stderr)
+        return 1 if run_dir.nil?
+
+        all_examples = read_json(File.join(run_dir, 'all_examples.json'))
+        match = find_example(all_examples, args.first)
+        return no_match(args.first, all_examples, stderr) if match.nil?
+
+        print_explanation(stdout, match, run_dir)
+        0
+      rescue StandardError => e
+        stderr.puts "explain: #{e.class}: #{e.message}"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.resolve_run_dir(cache_path, stderr)
+        last_run_path = File.join(cache_path, 'last_run.json')
+        unless File.file?(last_run_path)
+          stderr.puts "explain: no last_run.json at #{cache_path} — run rspec first"
+          return nil
+        end
+
+        run_id = JSON.parse(File.read(last_run_path, encoding: 'UTF-8'))['run_id']
+        run_dir = File.join(cache_path, run_id.to_s)
+        unless File.directory?(run_dir)
+          stderr.puts "explain: run_id #{run_id} directory missing at #{run_dir}"
+          return nil
+        end
+
+        run_dir
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.no_match(query, all_examples, stderr)
+        stderr.puts "explain: no example matching #{query.inspect}"
+        stderr.puts "  cache has #{all_examples.size} examples; pass an example_id or substring of description"
+        1
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_help(stdout)
+        stdout.puts <<~HELP
+          Usage: rspec-tracer explain <example_id_or_substring>
+
+          Show why an example is scheduled to run or skip. Matches against
+          example_id exactly first, then falls back to a substring match
+          on the example's full_description. Requires a prior rspec run.
+        HELP
+        0
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.read_json(path)
+        return {} unless File.file?(path)
+
+        parsed = JSON.parse(File.read(path, encoding: 'UTF-8'))
+        parsed.is_a?(Hash) ? parsed : {}
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.find_example(all_examples, query)
+        return all_examples[query] if all_examples.key?(query)
+
+        all_examples.find do |id, meta|
+          meta = {} unless meta.is_a?(::Hash)
+          desc = meta['full_description'] || meta['description'] || ''
+          id.include?(query) || desc.include?(query)
+        end&.last
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_explanation(stdout, meta, run_dir)
+        meta = {} unless meta.is_a?(::Hash)
+        format_lines(meta).each { |line| stdout.puts line }
+        print_dependency_summary(stdout, meta, run_dir)
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.format_lines(meta)
+        id = first_non_nil(meta, 'example_id', 'id') || '<unknown>'
+        file = first_non_nil(meta, 'rerun_file_name', 'file_name')
+        line = first_non_nil(meta, 'rerun_line_number', 'line_number')
+        status = meta.dig('execution_result', 'status') || meta['status'] || 'unknown'
+        [
+          "id:           #{id}",
+          "description:  #{first_non_nil(meta, 'full_description', 'description')}",
+          "location:     #{file}:#{line}",
+          "last status:  #{status}",
+          "run reason:   #{meta['run_reason'] || '<not recorded>'}"
+        ]
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.first_non_nil(meta, *keys)
+        keys.each { |k| return meta[k] unless meta[k].nil? }
+        nil
+      end
+
+      # Internal helper for the tracer pipeline.
+      # @api private
+      def self.print_dependency_summary(stdout, meta, run_dir)
+        deps_path = File.join(run_dir, 'dependency.json')
+        return unless File.file?(deps_path)
+
+        deps = read_json(deps_path)
+        id = meta['example_id'] || meta['id']
+        files = Array(deps[id])
+        stdout.puts "dependencies: #{files.size} files tracked"
+        files.first(10).each { |f| stdout.puts "  - #{f}" }
+        stdout.puts "  ... (#{files.size - 10} more)" if files.size > 10
+      end
+    end
+  end
+end