test_impact 0.2.0

data/lib/test_impact/map_serializer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'zlib'
+require 'stringio'
+require 'time'
+
+module TestImpact
+  # Reads and writes Map as gzip-compressed JSON. Unreadable payloads are
+  # raised as MapFormatError / SchemaVersionError so callers can fall back.
+  module MapSerializer
+    class << self
+      def dump(map, io_or_path)
+        bytes = dump_bytes(map)
+        if io_or_path.is_a?(String)
+          File.binwrite(io_or_path, bytes)
+        else
+          io_or_path.write(bytes)
+        end
+      end
+
+      def load(io_or_path)
+        bytes =
+          if io_or_path.is_a?(String)
+            File.binread(io_or_path)
+          else
+            io_or_path.read
+          end
+        load_bytes(bytes)
+      end
+
+      def dump_bytes(map)
+        payload = {
+          'schema_version' => map.schema_version,
+          'generated_at' => to_iso8601(map.generated_at),
+          'commit_sha' => map.commit_sha,
+          'branch' => map.branch,
+          'collector' => map.collector,
+          'known_spec_files' => map.known_spec_files.to_a.sort,
+          'index' => map.index.transform_values { |specs| specs.to_a.sort },
+        }
+
+        io = StringIO.new
+        io.set_encoding(Encoding::BINARY)
+        gz = Zlib::GzipWriter.new(io)
+        gz.write(JSON.generate(payload))
+        gz.close
+        io.string
+      end
+
+      def load_bytes(bytes)
+        io = StringIO.new(bytes)
+        gz = Zlib::GzipReader.new(io)
+        json = gz.read
+        gz.close
+
+        build_map(JSON.parse(json))
+      end
+
+      private
+
+      def build_map(data)
+        if data['schema_version'] != Map::SCHEMA_VERSION
+          raise SchemaVersionError, "unsupported schema_version: #{data['schema_version'].inspect}"
+        end
+
+        Map.new(
+          schema_version: data['schema_version'],
+          generated_at: Time.parse(data['generated_at']),
+          commit_sha: data['commit_sha'],
+          branch: data['branch'],
+          collector: data['collector'],
+          known_spec_files: data['known_spec_files'],
+          index: data['index']
+        )
+      rescue TypeError, NoMethodError, ArgumentError => e
+        # Missing or malformed fields (nil generated_at, non-hash index, ...)
+        raise MapFormatError, "malformed map payload: #{e.message}"
+      end
+
+      def to_iso8601(generated_at)
+        time = generated_at.is_a?(String) ? Time.parse(generated_at) : generated_at
+        # getutc (not utc/gmtime) so the caller's Time object is not mutated
+        time.getutc.iso8601
+      end
+    end
+  end
+end

data/lib/test_impact/path_matcher.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TestImpact
+  # The single source of pattern matching semantics for the config keys that
+  # take patterns. global_files, always_run and ignore are pure globs;
+  # collector.ignored_paths also accepts a plain path prefix (see
+  # prefix_or_glob_match?).
+  module PathMatcher
+    # FNM_PATHNAME is required for "**" to match across directory levels.
+    # FNM_DOTMATCH lets "**/*.yml" pick up dotfiles such as ".rubocop.yml".
+    FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+    # Glob metacharacters; a pattern without any of them is a plain literal.
+    GLOB_CHARS = /[*?\[\]{}]/
+
+    def self.match?(pattern, path)
+      File.fnmatch?(pattern, path, FLAGS)
+    end
+
+    def self.any_match?(patterns, path)
+      Array(patterns).any? { |pattern| match?(pattern, path) }
+    end
+
+    def self.glob?(pattern)
+      GLOB_CHARS.match?(pattern)
+    end
+
+    # collector.ignored_paths predates glob support, so a pattern without
+    # metacharacters keeps its original "path prefix" meaning: the default
+    # 'vendor/' would match nothing as a glob.
+    def self.prefix_or_glob_match?(pattern, path)
+      glob?(pattern) ? match?(pattern, path) : path.start_with?(pattern)
+    end
+  end
+end

data/lib/test_impact/paths.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'pathname'
+
+module TestImpact
+  # Resolves the repository root and converts between absolute paths and the
+  # repo-relative paths the map is keyed by.
+  module Paths
+    class << self
+      def repo_root
+        @repo_root ||=
+          begin
+            stdout, status = Open3.capture2('git', 'rev-parse', '--show-toplevel')
+            status.success? ? stdout.strip : Dir.pwd
+          rescue StandardError
+            Dir.pwd
+          end
+      end
+
+      def relative(abs_path)
+        Pathname.new(abs_path).relative_path_from(root_pathname).to_s
+      end
+
+      def absolute(rel_path)
+        File.expand_path(rel_path, repo_root)
+      end
+
+      private
+
+      # Cached per repo_root value so stubs and re-memoization stay consistent.
+      def root_pathname
+        root = repo_root
+        @root_pathname = Pathname.new(root) if @root_pathname.nil? || @root_pathname.to_s != root
+        @root_pathname
+      end
+    end
+  end
+end

data/lib/test_impact/plan_result.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TestImpact
+  # Outcome of planning: run everything (:all, with a reason), a selected set
+  # of specs (:partial), or nothing at all (:none).
+  class PlanResult
+    attr_reader :mode, :spec_files, :reason
+
+    def self.all(reason)
+      new(mode: :all, spec_files: [], reason:)
+    end
+
+    def self.partial(spec_files)
+      spec_files = spec_files.to_a.uniq.sort
+      new(mode: spec_files.empty? ? :none : :partial, spec_files:, reason: nil)
+    end
+
+    def initialize(mode:, spec_files:, reason:)
+      @mode = mode
+      @spec_files = spec_files
+      @reason = reason
+    end
+
+    def ==(other)
+      other.is_a?(PlanResult) &&
+        mode == other.mode &&
+        spec_files == other.spec_files &&
+        reason == other.reason
+    end
+    alias eql? ==
+
+    def hash
+      [mode, spec_files, reason].hash
+    end
+  end
+end

data/lib/test_impact/planner.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module TestImpact
+  # Classifies the files changed since the merge-base and turns them into a
+  # PlanResult, degrading to a full run whenever the map cannot be trusted.
+  # The classify_* methods all serve the single job of deciding what a changed
+  # file implies, so splitting them out would scatter one decision across classes.
+  class Planner # rubocop:disable Metrics/ClassLength
+    IGNORABLE_EXTENSIONS = ['.md', '.txt', '.adoc'].freeze
+    # Ruby sources and view templates. ActionView compiles templates under
+    # their absolute path, so DDCov records them like any other source file.
+    TRACKED_EXTENSIONS = ['.rb', '.erb', '.haml', '.slim', '.jbuilder'].freeze
+
+    def initialize(map:, config:, git: Git.new)
+      @map = map
+      @config = config
+      @git = git
+    end
+
+    def plan(base: nil, include_uncommitted: false)
+      changed = changed_files_or_reason(base || config.base, include_uncommitted:)
+      return PlanResult.all(changed) if changed.is_a?(String)
+
+      spec_files = Set.new
+      all_reason = nil
+
+      changed.each do |change|
+        all_reason = classify(change, spec_files)
+        break if all_reason
+      end
+
+      return PlanResult.all(all_reason) if all_reason
+
+      apply_always_run(spec_files)
+      spec_files.select! { |path| File.exist?(Paths.absolute(path)) }
+
+      PlanResult.partial(spec_files)
+    end
+
+    private
+
+    attr_reader :map, :config, :git
+
+    # Returns the changed files for base_ref, or a String reason when the diff
+    # cannot be trusted and the caller must degrade to a full run.
+    def changed_files_or_reason(base_ref, include_uncommitted:)
+      return 'no map available or backend invalid' if invalid_map?
+
+      stale_reason = staleness_reason(base_ref)
+      return stale_reason if stale_reason
+
+      merge_base_sha = git.merge_base(base_ref)
+      return 'could not compute merge-base (shallow clone? try fetch-depth: 0 in checkout)' unless merge_base_sha
+
+      git.changed_files(merge_base_sha, include_uncommitted:) ||
+        "could not compute git diff against #{merge_base_sha}"
+    end
+
+    def invalid_map?
+      map.nil? || map.empty? || !map.valid_backend?
+    end
+
+    def staleness_reason(base_ref)
+      if map.generated_at < (Time.now - (config.max_age_days * 86_400))
+        return "map is older than max_age_days (#{config.max_age_days})"
+      end
+
+      unless git.in_history?(map.commit_sha, base_ref)
+        return "map commit_sha #{map.commit_sha} not found in #{base_ref} history"
+      end
+
+      nil
+    end
+
+    # Returns an "all" reason string if this change forces a full run, otherwise nil
+    # (and mutates spec_files as a side effect).
+    def classify(change, spec_files)
+      # ignore runs first so it can subtract from global_files (carving
+      # config/locales/** out of the default config/**/*). Suppressing the
+      # "unknown file type" fallback alone would only need it in
+      # classify_other; winning over global_files is what buys the top slot,
+      # and what makes the rename rule below necessary.
+      return nil if ignored_change?(change)
+
+      path = change[:path]
+
+      global_reason = global_change_reason(change)
+      return global_reason if global_reason
+
+      return classify_as_spec(change, spec_files) if spec_file?(path)
+
+      # A file renamed away from a tracked path still carries its old
+      # coverage, so the old extension counts too — its dependent specs must
+      # not be silently dropped.
+      if tracked_file?(path) || (change[:old_path] && tracked_file?(change[:old_path]))
+        return classify_tracked(change, spec_files)
+      end
+
+      classify_other(change)
+    end
+
+    # Unlike global_change_reason, which reacts to either side of a rename,
+    # a rename is only ignored when BOTH sides match. Ignoring
+    # "R lib/foo.rb -> docs/foo.rb" on a docs/**/* pattern would silently drop
+    # the specs the old path still covers: ignore asserts that a file has no
+    # impact, not that its history had none.
+    def ignored_change?(change)
+      return false unless ignored_file?(change[:path])
+
+      old_path = change[:old_path]
+      old_path.nil? || ignored_file?(old_path)
+    end
+
+    # A rename away from a global location is still a change to that
+    # global file — it must not slip past the safeguard.
+    def global_change_reason(change)
+      return "global file changed: #{change[:path]}" if global_file?(change[:path])
+      return "global file changed: #{change[:old_path]}" if change[:old_path] && global_file?(change[:old_path])
+
+      nil
+    end
+
+    # A source file renamed into a spec path still carries its old coverage —
+    # pull its dependents (or fall back) in addition to scheduling the new
+    # spec itself.
+    def classify_as_spec(change, spec_files)
+      classify_spec(change, spec_files)
+
+      old_path = change[:old_path]
+      return nil unless old_path && tracked_file?(old_path) && !spec_file?(old_path)
+
+      classify_renamed_tracked(change, spec_files)
+    end
+
+    # Spec files are never indexed as coverage sources (Recorder skips spec/),
+    # so a changed spec only schedules itself. Non-spec helpers under spec/
+    # (support files etc.) fall through to the uncovered-file fallback instead.
+    def classify_spec(change, spec_files)
+      case change[:status]
+      when 'A', 'M', 'R'
+        spec_files << change[:path]
+      when 'D'
+        # excluded: do nothing
+      end
+
+      nil
+    end
+
+    def classify_tracked(change, spec_files)
+      case change[:status]
+      when 'R'
+        classify_renamed_tracked(change, spec_files)
+      else # "A", "M", "D" — an uncovered file always forces a full run
+        pull_covered_specs_or_fallback(change[:path], spec_files)
+      end
+    end
+
+    # The map predates the rename, so the old path carries the known
+    # dependents; a covered old path must not force a full run just because
+    # the new name is absent from the map.
+    def classify_renamed_tracked(change, spec_files)
+      covered_old = map&.covered?(change[:old_path])
+      spec_files.merge(map.specs_for(change[:old_path])) if covered_old
+
+      if map&.covered?(change[:path])
+        spec_files.merge(map.specs_for(change[:path]))
+        nil
+      elsif covered_old
+        nil
+      else
+        "uncovered file changed: #{change[:path]}"
+      end
+    end
+
+    def pull_covered_specs_or_fallback(path, spec_files)
+      if map&.covered?(path)
+        spec_files.merge(map.specs_for(path))
+        nil
+      else
+        "uncovered file changed: #{path}"
+      end
+    end
+
+    def classify_other(change)
+      path = change[:path]
+      ext = File.extname(path)
+
+      return nil if IGNORABLE_EXTENSIONS.include?(ext)
+
+      "unknown file type changed: #{path}"
+    end
+
+    def apply_always_run(spec_files)
+      return if config.always_run.empty?
+
+      candidates = Set.new(spec_files)
+      candidates.merge(map.known_spec_files) if map
+
+      candidates.each do |spec_path|
+        next unless PathMatcher.any_match?(config.always_run, spec_path)
+        next unless File.exist?(Paths.absolute(spec_path))
+
+        spec_files << spec_path
+      end
+    end
+
+    def global_file?(path)
+      PathMatcher.any_match?(config.global_files, path)
+    end
+
+    def ignored_file?(path)
+      PathMatcher.any_match?(config.ignore, path)
+    end
+
+    def spec_file?(path)
+      path.end_with?('_spec.rb') && path.start_with?('spec/')
+    end
+
+    # A file that can appear as a key in the coverage map.
+    def tracked_file?(path)
+      TRACKED_EXTENSIONS.include?(File.extname(path))
+    end
+  end
+end

data/lib/test_impact/recorder.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'securerandom'
+require 'socket'
+
+require 'test_impact/paths'
+require 'test_impact/path_matcher'
+require 'test_impact/git'
+require 'test_impact/map'
+require 'test_impact/map_serializer'
+
+module TestImpact
+  # Drives the coverage backend around each example and writes this process's
+  # results to a part-*.json.gz file for `test-impact merge` to combine.
+  class Recorder
+    DEFAULT_PART_DIR = 'tmp/test_impact'
+
+    attr_reader :backend, :config, :index, :known_spec_files
+
+    def initialize(backend:, config:)
+      @backend = backend
+      @config = config
+      @index = {}
+      @known_spec_files = Set.new
+      @written = false
+      @ignored_paths = Array(config.collector['ignored_paths'])
+    end
+
+    def start_example
+      backend.start
+    end
+
+    def finish_example(spec_abs_path)
+      covered = backend.stop || {}
+      spec_rel = spec_abs_path && Paths.relative(spec_abs_path)
+      return unless inside_repo?(spec_rel)
+
+      covered.each_key { |abs| record_covered(abs, spec_rel) }
+    end
+
+    def record_known_spec_files(paths)
+      Array(paths).each do |path|
+        rel = Paths.relative(path)
+        next unless inside_repo?(rel)
+
+        @known_spec_files << rel
+      end
+    end
+
+    def write_part(dir = ENV.fetch('TEST_IMPACT_PART_DIR', DEFAULT_PART_DIR))
+      return if @written
+
+      FileUtils.mkdir_p(dir)
+
+      # commit_sha is a hard requirement for the plan side: Planner treats a
+      # map whose commit is no longer reachable from the base ref as stale
+      # (force-push detection). branch is informational (info command).
+      git = Git.new
+      map = Map.build(
+        commit_sha: git.head_sha,
+        branch: git.head_branch,
+        collector: collector_metadata,
+        known_spec_files: @known_spec_files,
+        index: @index
+      )
+
+      path = File.join(dir, part_filename)
+      MapSerializer.dump(map, path)
+      # Only flip after a successful write so the at_exit fallback can retry
+      # when the after(:suite) attempt fails midway.
+      @written = true
+      path
+    end
+
+    private
+
+    def record_covered(abs, spec_rel)
+      rel = Paths.relative(abs)
+      return unless inside_repo?(rel)
+      return if spec_file?(rel, spec_rel)
+      return if ignored?(rel)
+
+      (@index[rel] ||= Set.new) << spec_rel
+    end
+
+    def collector_metadata
+      {
+        'backend' => backend.name,
+        'allocation_tracing' => config.collector['allocation_tracing'] ? true : false,
+      }
+    end
+
+    def part_filename
+      "part-#{Process.pid}-#{Socket.gethostname}-#{SecureRandom.hex(4)}.json.gz"
+    end
+
+    def inside_repo?(rel)
+      !rel.nil? && !rel.start_with?('..')
+    end
+
+    def ignored?(rel)
+      @ignored_paths.any? { |pattern| PathMatcher.prefix_or_glob_match?(pattern, rel) }
+    end
+
+    # spec/ files are intentionally never indexed as sources; Planner relies on
+    # this contract (changed specs run themselves, other spec/ files fall back).
+    def spec_file?(rel, spec_rel)
+      rel == spec_rel || rel.start_with?('spec/')
+    end
+  end
+end

data/lib/test_impact/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TestImpact
+  VERSION = '0.2.0'
+end

data/lib/test_impact.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'test_impact/version'
+require 'test_impact/paths'
+require 'test_impact/path_matcher'
+require 'test_impact/config'
+require 'test_impact/map'
+require 'test_impact/map_serializer'
+
+# Test Impact Analysis for Ruby: records which source files each spec touches,
+# then plans a minimal spec set from a git diff.
+module TestImpact
+  class Error < StandardError; end
+  class SchemaVersionError < Error; end
+  class MapFormatError < Error; end
+  class CoverageUnavailableError < Error; end
+
+  class << self
+    attr_accessor :recorder
+  end
+end
+
+require 'test_impact/collector/coverage_backend'
+require 'test_impact/recorder'
+require 'test_impact/git'
+require 'test_impact/plan_result'
+require 'test_impact/planner'
+require 'test_impact/cli'

data/skills/impacted-specs/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: impacted-specs
+description: Use when you want to find which RSpec specs to run for locally changed code, including uncommitted changes. Refreshes the coverage map produced by the test_impact gem's GitHub Actions collect workflow, then runs `test-impact plan` to narrow the run down to the impacted specs. Triggers on requests like "run only the tests related to my changes", "which specs does this diff affect", "figure out the impacted specs", or "what should I run for the current changes".
+license: MIT
+---
+
+# impacted-specs
+
+This skill runs inside a **project that consumes the test_impact gem**. It determines which specs
+to run from local changes, including uncommitted ones.
+
+Prerequisites:
+- `gh` CLI is authenticated
+- The consuming project has the `test_impact` gem in its `Gemfile`
+- That project runs a collect workflow in GitHub Actions that uploads the coverage map as an
+  artifact named `test-impact-map`
+
+## Steps
+
+### 1. Refresh the base
+
+Check `base` in `.test_impact.yml` (defaults to `origin/main`) and fetch the corresponding remote
+branch:
+
+```sh
+git fetch origin main
+```
+
+Why: if the local `origin/main` is stale, the map's `commit_sha` fails the history reachability
+check and the plan degrades to a full run (`all`).
+
+### 2. Download the map (every time, auto-discovered)
+
+Do not judge freshness even if a local map exists — **always download the latest artifact and
+overwrite**. Do not depend on a specific workflow name:
+
+```sh
+run_id=$(gh api 'repos/{owner}/{repo}/actions/artifacts?name=test-impact-map&per_page=1' \
+  --jq '.artifacts[] | select(.expired == false) | .workflow_run.id' | head -1)
+rm -f .test_impact/map.json.gz
+gh run download "$run_id" -n test-impact-map -D .test_impact
+```
+
+Notes:
+- Test `expired` with an explicit `== false` comparison (`//` treats `false` as falsy and falls
+  back to the right-hand side, so an `enabled // true` style check misjudges it).
+- `gh run download` fails when a file of the same name already exists in the destination, so
+  remove it first with `rm -f`.
+- If `run_id` comes back empty (no artifact found), report to the user that the collect workflow
+  is not set up and stop here.
+
+### 3. Run plan
+
+```sh
+bundle exec test-impact plan --format json --include-uncommitted > /tmp/plan.json
+```
+
+`--format json` always exits 0. stdout is a single line of JSON:
+`{"mode":"all|partial|none","spec_files":[...],"reason":null|"..."}`.
+Diagnostics (mode / reason / spec_files count, etc.) go to stderr.
+
+### 4. Interpret the result
+
+- `mode: "partial"` → run only the selected specs:
+  ```sh
+  bundle exec rspec $(jq -r '.spec_files[]' /tmp/plan.json)
+  ```
+- `mode: "none"` → report to the user that there are no specs to run.
+- `mode: "all"` → **do not run the full suite on your own.** Report that a full run is required
+  along with `reason`, and ask the user how to proceed. Common `reason` values:
+  - `uncovered file changed: <path>` — a new or uncollected file was changed
+  - `no map available or backend invalid` — the map is missing or unusable
+
+## Caveats
+
+- If `.test_impact/` is not in the consuming project's `.gitignore`, the map itself is treated as
+  an untracked new file and triggers a full run.
+- In a shallow clone, merge-base computation fails and the plan degrades to a full run.
+- `--include-uncommitted` includes staged / unstaged / untracked changes in the diff, but never
+  modifies repository state (read-only).

data/test_impact.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/test_impact/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'test_impact'
+  spec.version = TestImpact::VERSION
+  spec.authors = ['aki77']
+
+  spec.summary = 'Test Impact Analysis for Ruby without Datadog backend'
+  spec.description = "Collects per-test coverage via datadog-ci's native extension " \
+                     'and selects impacted specs from git diff.'
+  spec.homepage = 'https://github.com/aki77/test_impact_analysis'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files =
+    Dir.chdir(__dir__) do
+      # The `-ja` skill variants are for repo contributors only; the gem ships the English ones.
+      `git ls-files -z -- lib exe skills README.md LICENSE.txt test_impact.gemspec`
+        .split("\x0")
+        .grep_v(%r{\Askills/.*-ja\.md\z})
+    end
+  spec.bindir = 'exe'
+  spec.executables = ['test-impact']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'datadog-ci', '>= 1.20', '< 2.0'
+  spec.add_dependency 'thor', '~> 1.3'
+end