test_impact 0.2.0

data/lib/test_impact/cli.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'fileutils'
+require 'json'
+require 'zlib'
+
+module TestImpact
+  # `test-impact` command line entry point: merges per-process coverage parts
+  # into a single map, and plans which specs a diff requires.
+  # Thor subcommands must live in one class to share its DSL and options, so
+  # splitting merge/info/plan out would break the command definitions.
+  class CLI < Thor # rubocop:disable Metrics/ClassLength
+    # Any unreadable map (schema mismatch, malformed payload, truncated gzip,
+    # corrupt JSON) must degrade to "no map" so plan falls back to a full run.
+    MAP_LOAD_ERRORS = [
+      TestImpact::SchemaVersionError, TestImpact::MapFormatError, Zlib::Error, JSON::ParserError
+    ].freeze
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'merge', 'Merge part-*.json.gz coverage maps into a single map'
+    method_option :input, type: :string, default: 'tmp/test_impact', desc: 'Directory containing part-*.json.gz files'
+    method_option :output, type: :string, default: '.test_impact/map.json.gz', desc: 'Output path for the merged map'
+    def merge
+      input_dir = options[:input]
+      output_path = options[:output]
+
+      part_paths = Dir.glob(File.join(input_dir, 'part-*.json.gz'))
+      die("no part-*.json.gz files found in #{input_dir}") if part_paths.empty?
+
+      merged = merge_parts(load_parts(part_paths), part_paths)
+
+      FileUtils.mkdir_p(File.dirname(output_path))
+      MapSerializer.dump(merged, output_path)
+
+      warn_merge_summary(merged, part_paths.size, output_path)
+    end
+
+    desc 'info', 'Show summary information about a test impact map'
+    method_option :map, type: :string, default: '.test_impact/map.json.gz', desc: 'Path to the map file'
+    def info
+      map_path = options[:map]
+
+      die("map file not found: #{map_path}") unless File.exist?(map_path)
+
+      begin
+        map = MapSerializer.load(map_path)
+      rescue *MAP_LOAD_ERRORS => e
+        die("could not read map #{map_path}: #{e.message}")
+      end
+
+      puts "schema_version: #{map.schema_version}"
+      puts "commit_sha: #{map.commit_sha}"
+      puts "branch: #{map.branch}"
+      puts "generated_at: #{map.generated_at}"
+      puts "backend: #{map.collector.fetch('backend', 'unknown')}"
+      puts "source_files: #{map.index.keys.size}"
+      puts "spec_files: #{map.spec_count}"
+      puts "known_spec_files: #{map.known_spec_files.size}"
+    end
+
+    desc 'plan', 'Print the spec files impacted by the current diff'
+    method_option :map, type: :string, default: '.test_impact/map.json.gz', desc: 'Path to the map file'
+    method_option :base, type: :string, desc: 'Base ref to diff against (overrides config and GITHUB_BASE_REF)'
+    method_option :format, type: :string, default: 'lines', enum: %w[lines json], desc: 'Output format'
+    method_option :fallback_to_all_exit_code,
+                  type: :numeric,
+                  default: 10,
+                  desc: 'Exit code used for lines format when mode is all'
+    method_option :include_uncommitted,
+                  type: :boolean,
+                  default: false,
+                  desc: 'Also consider staged, unstaged and untracked working tree changes'
+    def plan
+      map_path = options[:map]
+      config = Config.load
+      map = load_map_or_nil(map_path)
+
+      base = options.fetch(:base, normalized_github_base_ref) || config.base
+      result = Planner.new(map:, config:).plan(base:, include_uncommitted: options[:include_uncommitted])
+
+      warn "mode: #{result.mode}"
+      warn "reason: #{result.reason}" if result.reason
+      warn "spec_files: #{result.spec_files.size}"
+
+      if options[:format] == 'json'
+        print_plan_json(result)
+      else
+        print_plan_lines(result)
+      end
+    end
+
+    private
+
+    def load_parts(part_paths)
+      part_paths.map do |path|
+        MapSerializer.load(path)
+      rescue *MAP_LOAD_ERRORS => e
+        die("could not read part #{path}: #{e.message}")
+      end
+    end
+
+    def merge_parts(maps, part_paths)
+      base_commit_sha = maps.first.commit_sha
+
+      maps[1..].each_with_index.reduce(maps[0]) do |merged, (map, idx)|
+        if map.commit_sha != base_commit_sha
+          warn "warning: commit_sha mismatch in #{part_paths[idx + 1]} (#{map.commit_sha} != #{base_commit_sha})"
+        end
+        merged.merge(map)
+      end
+    end
+
+    def warn_merge_summary(merged, part_count, output_path)
+      warn "merged #{part_count} part(s) into #{output_path}"
+      warn "source files: #{merged.index.keys.size}, specs: #{merged.spec_count}, " \
+           "known_spec_files: #{merged.known_spec_files.size}"
+    end
+
+    def print_plan_json(result)
+      puts JSON.generate({ 'mode' => result.mode.to_s, 'spec_files' => result.spec_files, 'reason' => result.reason })
+      exit(0)
+    end
+
+    def print_plan_lines(result)
+      exit(options[:fallback_to_all_exit_code]) if result.mode == :all
+
+      puts result.spec_files.join("\n") unless result.spec_files.empty?
+      exit(0)
+    end
+
+    def die(message)
+      warn "error: #{message}"
+      exit(1)
+    end
+
+    def load_map_or_nil(map_path)
+      return nil unless File.exist?(map_path)
+
+      begin
+        MapSerializer.load(map_path)
+      rescue *MAP_LOAD_ERRORS => e
+        warn "warning: could not read map #{map_path}: #{e.message}"
+        nil
+      end
+    end
+
+    def normalized_github_base_ref
+      ref = ENV.fetch('GITHUB_BASE_REF', nil)
+      ref.nil? || ref.empty? ? nil : "origin/#{ref}"
+    end
+  end
+end

data/lib/test_impact/collector/coverage_backend.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'test_impact/collector/ddcov_backend'
+require 'test_impact/collector/null_backend'
+
+module TestImpact
+  module Collector
+    # Chooses the coverage backend for this process: the native ddcov backend
+    # when it loads, otherwise a hard failure unless the caller opted out.
+    module CoverageBackend
+      UNAVAILABLE_MESSAGE = 'test_impact: coverage backend unavailable, ' \
+                            'falling back to null backend because TEST_IMPACT_REQUIRE_COVERAGE ' \
+                            'opts out (no coverage will be collected)'
+
+      # Spelled generously on purpose: unlike an opt-in flag, a misspelled
+      # opt-out fails the collection job, and the typo only surfaces on the
+      # day the backend actually breaks.
+      OPT_OUT_VALUES = %w[0 false no off].freeze
+
+      def self.build(config)
+        # Bind once: both lookups memoize per parameter, so they must be
+        # asked about the very same one.
+        allocation_tracing = DdcovBackend.allocation_tracing?(config)
+        reason = DdcovBackend.unavailable_reason(use_allocation_tracing: allocation_tracing)
+        return DdcovBackend.new(config) if reason.nil?
+
+        # Collecting coverage is the only reason this process runs, so an
+        # unusable backend is a hard failure unless explicitly opted out of.
+        raise CoverageUnavailableError, unavailable_error_message(reason) unless opted_out?
+
+        warn UNAVAILABLE_MESSAGE
+        NullBackend.new
+      end
+
+      def self.opted_out?
+        OPT_OUT_VALUES.include?(ENV['TEST_IMPACT_REQUIRE_COVERAGE'].to_s.strip.downcase)
+      end
+
+      # Spelled out for operators who only ever see the CI log.
+      def self.unavailable_error_message(reason)
+        "test_impact: coverage backend unavailable (#{reason.class}: #{reason.message}). " \
+          'Set TEST_IMPACT_REQUIRE_COVERAGE=0 to fall back to the null backend instead ' \
+          '(the map is then tagged as invalid and every spec runs).'
+      end
+    end
+  end
+end

data/lib/test_impact/collector/ddcov_backend.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'test_impact/paths'
+
+module TestImpact
+  module Collector
+    # Coverage backend built on datadog-ci's native DDCov extension. Records
+    # the source files touched between #start and #stop.
+    class DdcovBackend
+      NATIVE_REQUIRE_PATH = "datadog_ci_native.#{RUBY_VERSION}_#{RUBY_PLATFORM}".freeze
+      DDCOV_CONST = 'Datadog::CI::TestImpactAnalysis::Coverage::DDCov'
+
+      class << self
+        # Probes with the same parameters the real instance will use
+        # (ignored_path and allocation tracing included), so a code path that
+        # only breaks under the real configuration still fails safe here.
+        def available?(use_allocation_tracing: true)
+          probe(use_allocation_tracing).nil?
+        end
+
+        # The exception that made the probe fail, or nil when the backend is
+        # available. Callers that turn unavailability into a hard failure need
+        # it to tell the user *why* ddcov could not load.
+        def unavailable_reason(use_allocation_tracing: true)
+          probe(use_allocation_tracing)
+        end
+
+        def allocation_tracing?(config)
+          config.collector['allocation_tracing'] ? true : false
+        end
+
+        # Must be the same value the instance passes, so the availability
+        # check exercises the real parameter shape (nil without Bundler).
+        def default_ignored_path
+          return nil unless defined?(Bundler)
+
+          Bundler.bundle_path.to_s
+        rescue StandardError
+          nil
+        end
+
+        def load_ddcov_class!
+          require NATIVE_REQUIRE_PATH
+          Object.const_get(DDCOV_CONST)
+        end
+
+        def build_instance(root:, ignored_path:, use_allocation_tracing:)
+          load_ddcov_class!.new(
+            root:,
+            ignored_path:,
+            threading_mode: :multi,
+            use_allocation_tracing:
+          )
+        end
+
+        def reset_memoization!
+          @probe = nil
+        end
+
+        private
+
+        # Memoizes one probe result per parameter: nil when ddcov works, the
+        # exception that broke it otherwise. Keeping "did it work" and "why
+        # not" in a single entry means the two can never disagree.
+        def probe(use_allocation_tracing)
+          @probe ||= {}
+          return @probe[use_allocation_tracing] if @probe.key?(use_allocation_tracing)
+
+          @probe[use_allocation_tracing] =
+            begin
+              build_instance(root: Paths.repo_root,
+                             ignored_path: default_ignored_path,
+                             use_allocation_tracing:)
+                .tap(&:start).stop
+              nil
+            rescue LoadError, StandardError => e
+              e
+            end
+        end
+      end
+
+      def initialize(config)
+        @ddcov = self.class.build_instance(
+          root: Paths.repo_root,
+          ignored_path: self.class.default_ignored_path,
+          use_allocation_tracing: self.class.allocation_tracing?(config)
+        )
+      end
+
+      def start
+        @ddcov.start
+      end
+
+      def stop
+        @ddcov.stop
+      end
+
+      def name
+        'ddcov'
+      end
+    end
+  end
+end

data/lib/test_impact/collector/null_backend.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module TestImpact
+  module Collector
+    # Fallback backend that records nothing. Used when coverage is unavailable
+    # and the caller opted out of failing; the resulting map stays invalid so
+    # planning degrades to a full run.
+    class NullBackend
+      def start
+        nil
+      end
+
+      def stop
+        {}
+      end
+
+      def name
+        'null'
+      end
+    end
+  end
+end

data/lib/test_impact/config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module TestImpact
+  # Settings loaded from .test_impact.yml, with defaults for the base ref,
+  # map staleness, always-run specs, global files, ignored files, and collector
+  # options.
+  class Config
+    DEFAULT_GLOBAL_FILES = [
+      'Gemfile',
+      'Gemfile.lock',
+      '*.gemspec',
+      '.ruby-version',
+      'Dockerfile',
+      'config/**/*',
+      'db/schema.rb',
+      'db/structure.sql',
+      'spec/spec_helper.rb',
+      'spec/rails_helper.rb',
+      'spec/factories/**/*',
+      'spec/fixtures/**/*',
+    ].freeze
+
+    DEFAULT_COLLECTOR = {
+      'allocation_tracing' => true,
+      'ignored_paths' => ['vendor/', 'tmp/'].freeze,
+    }.freeze
+
+    attr_reader :base, :max_age_days, :always_run, :global_files, :ignore, :collector
+
+    def self.load(path = nil)
+      path ||= File.join(Paths.repo_root, '.test_impact.yml')
+      raw = File.exist?(path) ? (YAML.safe_load_file(path) || {}) : {}
+      new(raw)
+    end
+
+    def initialize(raw = {})
+      raw = raw.transform_keys(&:to_s)
+
+      @base = value_or_default(raw, 'base', 'origin/main')
+      @max_age_days = value_or_default(raw, 'max_age_days', 7)
+      @always_run = value_or_default(raw, 'always_run', [])
+      @global_files = value_or_default(raw, 'global_files', DEFAULT_GLOBAL_FILES.dup)
+      @ignore = value_or_default(raw, 'ignore', [])
+      @collector = value_or_default(raw, 'collector', DEFAULT_COLLECTOR.dup)
+    end
+
+    private
+
+    # Unlike Hash#fetch, treats an explicitly nil value (e.g. a bare
+    # "collector:" line in YAML) as absent so defaults still apply. A Hash
+    # default is merged key-by-key with the same rule applied one level down,
+    # so a bare "ignored_paths:" nested under it falls back to the default too.
+    def value_or_default(raw, key, default)
+      value = raw[key]
+      return default if value.nil?
+
+      default.is_a?(Hash) ? default.merge(value.compact) : value
+    end
+  end
+end

data/lib/test_impact/frameworks/rspec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+return unless ENV['TEST_IMPACT_COLLECT'] == '1'
+
+require 'test_impact'
+require 'test_impact/collector/coverage_backend'
+require 'test_impact/recorder'
+
+test_impact_config = TestImpact::Config.load
+TestImpact.recorder = TestImpact::Recorder.new(
+  backend: TestImpact::Collector::CoverageBackend.build(test_impact_config),
+  config: test_impact_config
+)
+
+RSpec.configure do |config|
+  config.prepend_before(:each) { TestImpact.recorder.start_example }
+
+  config.append_after(:each) do |example|
+    TestImpact.recorder.finish_example(example.metadata[:absolute_file_path])
+  end
+
+  config.after(:suite) do
+    TestImpact.recorder.record_known_spec_files(RSpec.configuration.files_to_run)
+    TestImpact.recorder.write_part
+  end
+end
+
+at_exit { TestImpact.recorder&.write_part }

data/lib/test_impact/git.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+module TestImpact
+  # Thin wrapper over the git commands planning needs: merge-base lookup,
+  # name-status diffs (rename/copy aware), and reachability checks.
+  class Git
+    def initialize(repo_root: Paths.repo_root)
+      @repo_root = repo_root
+    end
+
+    def merge_base(base_ref)
+      stdout, status = run('merge-base', base_ref, 'HEAD')
+      status.success? ? stdout.strip : nil
+    end
+
+    # Returns nil when the diff itself fails, so callers can distinguish
+    # "no changes" ([]) from "could not compute the diff". Omitting the
+    # trailing HEAD diffs merge_base_sha against the working tree
+    # (staged + unstaged combined) instead of against the last commit.
+    def changed_files(merge_base_sha, include_uncommitted: false)
+      diff_args = ['diff', '--name-status', '-M', '-C', merge_base_sha]
+      diff_args << 'HEAD' unless include_uncommitted
+
+      stdout, status = run(*diff_args)
+      return nil unless status.success?
+
+      diffed = stdout.each_line.filter_map { |line| parse_diff_line(line) }
+      return diffed unless include_uncommitted
+
+      merge_untracked(diffed)
+    end
+
+    # True when sha is reachable from ref. A mere `cat-file -e` object check
+    # would also accept dangling objects left behind by a force-push.
+    def in_history?(sha, ref)
+      _, status = run('merge-base', '--is-ancestor', sha, ref)
+      status.success?
+    end
+
+    # On pull_request events actions/checkout checks out the synthetic
+    # refs/pull/N/merge commit, which exists in no branch history — a map
+    # recorded under it would always look stale to Planner#in_history?.
+    # The event payload carries the real head commit, so prefer it there.
+    def head_sha
+      pull_request_head_sha || rev_parse('HEAD')
+    end
+
+    # Detached HEAD (the default actions/checkout state) yields the literal
+    # string "HEAD"; only then is CI's branch name a valid substitute.
+    # GITHUB_HEAD_REF holds the source branch on pull_request events (where
+    # GITHUB_REF_NAME would be the synthetic "N/merge" ref). An empty result
+    # means git itself failed — keep it visible as "".
+    def head_branch
+      name = rev_parse('--abbrev-ref', 'HEAD')
+      return name unless name == 'HEAD'
+
+      ci_branch = [ENV.fetch('GITHUB_HEAD_REF', nil), ENV.fetch('GITHUB_REF_NAME', nil)].find { |v| v && !v.empty? }
+      ci_branch || name
+    end
+
+    private
+
+    def rev_parse(*)
+      stdout, status = run('rev-parse', *)
+      status.success? ? stdout.strip : ''
+    rescue StandardError
+      ''
+    end
+
+    # Only pull_request-shaped events carry pull_request.head.sha; on push
+    # GITHUB_EVENT_PATH is still set but the key is absent, so this returns
+    # nil and the plain HEAD lookup stands. dig raises TypeError when an
+    # intermediate value is not a Hash, so the rescue must cover it too.
+    def pull_request_head_sha
+      path = ENV.fetch('GITHUB_EVENT_PATH', nil)
+      return nil if path.nil? || path.empty? || !File.file?(path)
+
+      sha = JSON.parse(File.read(path)).dig('pull_request', 'head', 'sha')
+      sha if sha.is_a?(String) && !sha.empty?
+    rescue StandardError
+      nil
+    end
+
+    # Untracked files are new by definition, so they map straight to 'A'
+    # and cannot collide with the diff output.
+    def merge_untracked(diffed)
+      untracked = untracked_files
+      return nil unless untracked
+
+      diffed + untracked.map { |path| { status: 'A', path: } }
+    end
+
+    def untracked_files
+      stdout, status = run('ls-files', '--others', '--exclude-standard', '-z')
+      return nil unless status.success?
+
+      stdout.split("\0").reject(&:empty?)
+    end
+
+    def parse_diff_line(line)
+      fields = line.chomp.split("\t")
+      return nil if fields.empty?
+
+      raw_status, *paths = fields
+
+      case raw_status[0]
+      when 'R'
+        { status: 'R', path: paths[1], old_path: paths[0] }
+      when 'C'
+        # Copy lines list source then destination; only the destination is new.
+        { status: 'A', path: paths[1] }
+      else
+        { status: raw_status[0], path: paths[0] }
+      end
+    end
+
+    def run(*)
+      stdout, _stderr, status = Open3.capture3('git', '-C', @repo_root, *)
+      [stdout, status]
+    end
+  end
+end

data/lib/test_impact/map.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module TestImpact
+  # The coverage map handed between phases: which specs touch which source
+  # files, plus the commit it was built from and the backend that built it.
+  class Map
+    SCHEMA_VERSION = 1
+
+    attr_reader :schema_version, :generated_at, :commit_sha, :branch, :collector, :known_spec_files, :index
+
+    def self.build(commit_sha:, branch:, collector:, generated_at: Time.now, known_spec_files: [], index: {})
+      new(
+        schema_version: SCHEMA_VERSION,
+        generated_at:,
+        commit_sha:,
+        branch:,
+        collector:,
+        known_spec_files:,
+        index:
+      )
+    end
+
+    def initialize(schema_version:, generated_at:, commit_sha:, branch:, collector:, known_spec_files:, index:)
+      validate!(generated_at:, commit_sha:, branch:, collector:, known_spec_files:)
+
+      @schema_version = schema_version
+      @generated_at = generated_at
+      @commit_sha = commit_sha
+      @branch = branch
+      @collector = collector
+      @known_spec_files = Set.new(known_spec_files)
+      @index =
+        index.each_with_object({}) do |(k, v), h|
+          raise TypeError, "index value for #{k.inspect} must not be nil" if v.nil?
+
+          h[k] = Set.new(v)
+        end
+    end
+
+    def commit_sha_mismatch?(other)
+      commit_sha != other.commit_sha
+    end
+
+    # Metadata (generated_at, commit_sha, branch, collector) always comes from
+    # the newer of the two maps, so merge order cannot pair a fresh timestamp
+    # with a stale commit_sha.
+    def merge(other)
+      merged_index = index.each_with_object({}) { |(k, v), h| h[k] = v.dup }
+      other.index.each do |k, v|
+        merged_index[k] = (merged_index[k] || Set.new) | v
+      end
+
+      newer = other.generated_at >= generated_at ? other : self
+
+      self.class.new(
+        schema_version: SCHEMA_VERSION,
+        generated_at: newer.generated_at,
+        commit_sha: newer.commit_sha,
+        branch: newer.branch,
+        collector: merged_collector(newer:, other:),
+        known_spec_files: known_spec_files | other.known_spec_files,
+        index: merged_index
+      )
+    end
+
+    def specs_for(source_path)
+      index[source_path] || Set.new
+    end
+
+    def covered?(source_path)
+      index.key?(source_path)
+    end
+
+    def empty?
+      index.empty?
+    end
+
+    def spec_count
+      index.each_value.with_object(Set.new) { |specs, acc| acc.merge(specs) }.size
+    end
+
+    def valid_backend?
+      collector['backend'] != 'null'
+    end
+
+    def ==(other)
+      other.is_a?(Map) && comparable_fields == other.comparable_fields
+    end
+    alias eql? ==
+
+    def hash
+      comparable_fields.hash
+    end
+
+    protected
+
+    def comparable_fields
+      [schema_version, generated_at, commit_sha, branch, collector, known_spec_files, index]
+    end
+
+    private
+
+    # Set.new(nil) silently yields an empty Set; nils and wrong types here
+    # are malformed payloads and must raise so MapSerializer degrades them
+    # to MapFormatError instead of crashing later in Planner.
+    def validate!(generated_at:, commit_sha:, branch:, collector:, known_spec_files:)
+      raise TypeError, 'known_spec_files must not be nil' if known_spec_files.nil?
+      raise TypeError, 'collector must be a Hash' unless collector.is_a?(Hash)
+      raise TypeError, 'commit_sha must be a String' unless commit_sha.is_a?(String)
+      raise TypeError, 'branch must be a String' unless branch.is_a?(String)
+      raise TypeError, 'generated_at must be a Time' unless generated_at.is_a?(Time)
+    end
+
+    # A "null" backend in any merged part means part of the coverage is missing,
+    # so the merged map must stay invalid regardless of merge order.
+    def merged_collector(newer:, other:)
+      if collector['backend'] == 'null' || other.collector['backend'] == 'null'
+        newer.collector.merge('backend' => 'null')
+      else
+        newer.collector
+      end
+    end
+  end
+end