minitest-heat 1.1.0 → 1.3.0

data/RELEASING.md

@@ -0,0 +1,191 @@
+# Releasing Minitest Heat
+
+## Quick Reference
+
+```bash
+# 1. Update version and changelog
+# 2. Commit and push
+git add -A && git commit -m "Release vX.Y.Z" && git push
+
+# 3. Tag and push
+git tag vX.Y.Z && git push origin vX.Y.Z
+
+# Done - automation handles the rest
+```
+
+## How It Works
+
+Releases are fully automated via GitHub Actions:
+
+1. **Branch protection** requires CI to pass before merging to `main`
+2. When you push a version tag, the release workflow:
+   - Validates the tag points to a commit on `main` (ensures CI passed)
+   - Builds and publishes the gem to RubyGems
+   - Creates a GitHub Release with changelog excerpt
+
+No redundant test runs. If it's on `main`, it already passed CI.
+
+## Release Steps
+
+### 1. Update Version
+
+Edit `lib/minitest/heat/version.rb`:
+
+```ruby
+VERSION = 'X.Y.Z'
+```
+
+### 2. Update CHANGELOG
+
+Move items from `[Unreleased]` to a new version section:
+
+```markdown
+## [Unreleased]
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Added
+- New feature description
+
+### Fixed
+- Bug fix description
+```
+
+### 3. Commit, Tag, Push
+
+```bash
+git add lib/minitest/heat/version.rb CHANGELOG.md
+git commit -m "Release vX.Y.Z"
+git push origin main
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### 4. Verify
+
+- Watch the [Actions tab](https://github.com/garrettdimon/minitest-heat/actions) for workflow completion
+- Check [RubyGems](https://rubygems.org/gems/minitest-heat) for the new version
+- Check [GitHub Releases](https://github.com/garrettdimon/minitest-heat/releases) for the release page
+
+## Versioning Policy
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (x.0.0): Breaking changes to public API or configuration
+- **MINOR** (0.x.0): New features, deprecations
+- **PATCH** (0.0.x): Bug fixes, documentation
+
+### What's a Breaking Change?
+
+- Removing or renaming public classes/methods
+- Changing method signatures incompatibly
+- Changing default configuration behavior
+- Dropping Ruby version support
+
+## Local Tools
+
+### Full Preflight Check
+
+Run all checks before pushing:
+
+```bash
+bundle exec rake release:preflight
+```
+
+This runs tests, security audit, and release validation in sequence.
+
+### Individual Tasks
+
+| Task | Purpose |
+|------|---------|
+| `rake release:preflight` | Run all checks (test, audit, check) |
+| `rake release:check` | Validate version format, changelog entry, git state |
+| `rake release:audit` | Check for vulnerable dependencies |
+| `rake release:dry_run` | Build gem locally, show contents and size |
+| `rake test` | Run test suite |
+
+### Preview a Release
+
+Before tagging, preview what the gem will contain:
+
+```bash
+bundle exec rake release:dry_run
+```
+
+This builds the gem, displays its contents and size, then cleans up.
+
+## One-Time Setup
+
+### RubyGems Trusted Publishing
+
+1. Go to [rubygems.org/profile/oidc/pending_trusted_publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers)
+2. Add trusted publisher:
+   - **Gem name:** `minitest-heat`
+   - **Repository owner:** `garrettdimon`
+   - **Repository name:** `minitest-heat`
+   - **Workflow filename:** `release.yml`
+   - **Environment:** `rubygems`
+
+### GitHub Environment
+
+1. Go to repository Settings > Environments
+2. Create environment named `rubygems`
+3. (Optional) Add required reviewers for extra safety
+
+### Repository Ruleset
+
+1. Go to repository Settings > Rules > Rulesets
+2. Edit the `main` ruleset (or create one targeting the default branch)
+3. Enable "Require status checks to pass" with these checks:
+   - `Security`
+   - `Test (Ruby 3.1)`
+   - `Test (Ruby 3.2)`
+   - `Test (Ruby 3.3)`
+   - `Test (Ruby 3.4)`
+   - `Test (Ruby 4.0)`
+   - `Changelog`
+   - `Version`
+
+## Troubleshooting
+
+### Release workflow fails with "must point to commit on main"
+
+You tagged a commit that isn't on the main branch. Delete the tag and re-tag a commit on main:
+
+```bash
+git tag -d vX.Y.Z              # Delete local tag
+git push origin :vX.Y.Z        # Delete remote tag
+git checkout main
+git pull
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+### "You do not have permission to push to this gem"
+
+The RubyGems trusted publisher isn't configured, or the environment name doesn't match. Check the one-time setup steps above.
+
+### Forgot to update CHANGELOG
+
+Delete the tag, update CHANGELOG, amend the commit, re-tag:
+
+```bash
+git tag -d vX.Y.Z
+git push origin :vX.Y.Z
+# Update CHANGELOG.md
+git add CHANGELOG.md
+git commit --amend --no-edit
+git push --force-with-lease origin main
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+## Manual Release (Fallback)
+
+If automation fails and you need to publish manually:
+
+```bash
+bundle exec rake release
+```
+
+This builds the gem and pushes to RubyGems using your local credentials.

data/Rakefile

@@ -10,3 +10,120 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task default: :test
+
+# rubocop:disable Metrics/BlockLength
+namespace :release do
+  desc 'Run bundle-audit to check for vulnerable dependencies'
+  task :audit do
+    puts 'Running security audit...'
+    sh 'bundle exec bundle-audit check --update'
+  end
+
+  desc 'Validate version, changelog, and git state before release'
+  task :check do
+    require_relative 'lib/minitest/heat/version'
+    errors = ReleaseChecker.new(Minitest::Heat::VERSION).validate
+    if errors.any?
+      puts "\nRelease check failed:"
+      errors.each { |e| puts "  - #{e}" }
+      exit 1
+    else
+      puts 'All release checks passed.'
+    end
+  end
+
+  desc 'Run all pre-release checks (tests, audit, release:check)'
+  task preflight: %i[test audit check] do
+    puts "\nAll preflight checks passed. Ready to release."
+  end
+
+  desc 'Build gem locally and show contents (dry run)'
+  task :dry_run do
+    require_relative 'lib/minitest/heat/version'
+    DryRun.new(Minitest::Heat::VERSION).run
+  end
+end
+# rubocop:enable Metrics/BlockLength
+
+# Validates release readiness
+class ReleaseChecker
+  def initialize(version)
+    @version = version
+    @errors = []
+  end
+
+  def validate
+    puts "Checking release readiness for v#{@version}..."
+    check_version_format
+    check_changelog
+    check_git_clean
+    check_main_branch
+    @errors
+  end
+
+  private
+
+  def check_version_format
+    return if @version.match?(/\A\d+\.\d+\.\d+\z/)
+
+    @errors << "Version '#{@version}' is not valid semver (expected X.Y.Z)"
+  end
+
+  def check_changelog
+    changelog = File.read('CHANGELOG.md')
+    return if changelog.include?("[#{@version}]")
+
+    @errors << "CHANGELOG.md has no entry for version #{@version}"
+  end
+
+  def check_git_clean
+    return if `git status --porcelain`.empty?
+
+    @errors << 'Working directory has uncommitted changes'
+  end
+
+  def check_main_branch
+    current_branch = `git branch --show-current`.strip
+    return if current_branch == 'main'
+
+    @errors << "Not on main branch (currently on '#{current_branch}')"
+  end
+end
+
+# Builds gem and displays contents without publishing
+class DryRun
+  def initialize(version)
+    @version = version
+    @gem_file = "minitest-heat-#{version}.gem"
+  end
+
+  def run
+    build || abort('Gem build failed')
+    show_contents
+    show_size
+  ensure
+    cleanup if File.exist?(@gem_file)
+  end
+
+  private
+
+  def build
+    puts "Building #{@gem_file}..."
+    system 'gem build minitest-heat.gemspec --silent'
+  end
+
+  def show_contents
+    puts "\nGem contents:"
+    system "tar -tf #{@gem_file}"
+  end
+
+  def show_size
+    size = File.size(@gem_file)
+    puts "\nGem size: #{(size / 1024.0).round(1)} KB"
+  end
+
+  def cleanup
+    File.delete(@gem_file)
+    puts "Cleaned up #{@gem_file}"
+  end
+end

data/lib/minitest/heat/backtrace/line_count.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Minitest
+  module Heat
+    class Backtrace
+      # Determines an optimal line count for backtrace locations in order to have relevant
+      #   information but keep the backtrace as compact as possible
+      class LineCount
+        DEFAULT_LINE_COUNT = 20
+
+        attr_accessor :locations
+
+        def initialize(locations)
+          @locations = locations
+        end
+
+        def earliest_project_location
+          locations.rindex { |element| element.project_file? }
+        end
+
+        def max_location
+          [locations.size - 1, 0].max
+        end
+
+        def limit
+          return 0 if locations.empty?
+
+          # Find the minimum relevant index, then add 1 to convert from index to count
+          [
+            DEFAULT_LINE_COUNT - 1,
+            earliest_project_location,
+            max_location
+          ].compact.min + 1
+        end
+      end
+    end
+  end
+end

data/lib/minitest/heat/backtrace/line_parser.rb

@@ -10,8 +10,10 @@ module Minitest
       module LineParser
         # Parses a line from a backtrace in order to convert it to usable components
         def self.read(raw_text)
-          raw_pathname, raw_line_number, raw_container = raw_text.split(':')
-          raw_container = raw_container.delete_prefix('in `').delete_suffix("'")
+          return nil if raw_text.nil? || raw_text.empty?
+
+          raw_pathname, raw_line_number, raw_container = raw_text.to_s.split(':')
+          raw_container = raw_container&.delete_prefix('in `')&.delete_suffix("'")
 
           ::Minitest::Heat::Location.new(
             pathname: raw_pathname,

data/lib/minitest/heat/backtrace.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative 'backtrace/line_count'
 require_relative 'backtrace/line_parser'
 
 module Minitest
@@ -30,7 +31,7 @@ module Minitest
       def locations
         return [] if raw_backtrace.nil?
 
-        @locations ||= raw_backtrace.map { |entry| Backtrace::LineParser.read(entry) }
+        @locations ||= raw_backtrace.map { |entry| Backtrace::LineParser.read(entry) }.compact
       end
 
       # All entries from the backtrace within the project and sorted with the most recently modified

data/lib/minitest/heat/configuration.rb

@@ -6,12 +6,17 @@ module Minitest
   module Heat
     # For managing configuration options on how Minitest Heat should handle results
     class Configuration
+      DEFAULTS = {
+        slow_threshold:           1.0,
+        painfully_slow_threshold: 3.0
+      }.freeze
+
       attr_accessor :slow_threshold,
                     :painfully_slow_threshold
 
       def initialize
-        @slow_threshold = 1.0
-        @painfully_slow_threshold = 3.0
+        @slow_threshold           = DEFAULTS[:slow_threshold]
+        @painfully_slow_threshold = DEFAULTS[:painfully_slow_threshold]
       end
     end
   end

data/lib/minitest/heat/hit.rb

@@ -63,33 +63,49 @@ module Minitest
       #
       # @return [Integer] the problem weight for the file
       def weight
-        weight = 0
-        issues.each_pair do |type, values|
-          weight += values.size * WEIGHTS.fetch(type, 0)
-        end
-        weight
+        issues.sum { |type, values| values.size * WEIGHTS.fetch(type, 0) }
       end
 
       # The total issue count for the file across all issue types. Includes duplicates if they exist
       #
       # @return [Integer] the sum of the counts for all line numbers for all issue types
       def count
-        count = 0
-        issues.each_pair do |_type, values|
-          count += values.size
-        end
-        count
+        issues.sum { |_type, values| values.size }
       end
 
       # The full set of unique line numbers across all issue types
       #
       # @return [Array<Integer>] the full set of unique offending line numbers for the hit
       def line_numbers
-        line_numbers = []
-        issues.each_pair do |_type, values|
-          line_numbers += values
+        issues.values.flatten.uniq.sort
+      end
+
+      # Generates a hash representation for JSON serialization
+      #
+      # @return [Hash] hit data with file, weight, and line details
+      def to_h
+        {
+          file: relative_path,
+          weight: weight,
+          lines: lines_summary
+        }
+      end
+
+      private
+
+      def relative_path
+        pathname.to_s.delete_prefix("#{Dir.pwd}/")
+      end
+
+      def lines_summary
+        line_numbers.map do |line_num|
+          traces = lines[line_num.to_s] || []
+          {
+            line: line_num,
+            types: traces.map(&:type).uniq,
+            count: traces.size
+          }
         end
-        line_numbers.uniq.sort
       end
     end
   end

data/lib/minitest/heat/issue.rb

@@ -10,12 +10,12 @@ module Minitest
 
       TYPES = %i[error broken failure skipped painful slow].freeze
 
-      # Long-term, these could be configurable so that people can determine their own thresholds of
-      # pain for slow tests
-      SLOW_THRESHOLDS = {
-        slow: 1.0,
-        painful: 3.0
-      }.freeze
+      # # Long-term, these could be configurable so that people can determine their own thresholds of
+      # # pain for slow tests
+      # SLOW_THRESHOLDS = {
+      #   slow: 1.0,
+      #   painful: 3.0
+      # }.freeze
 
       attr_reader :assertions,
                   :locations,
@@ -120,14 +120,14 @@ module Minitest
       #
       # @return [Float] number of seconds after which a test is considered slow
       def slow_threshold
-        Minitest::Heat.configuration.slow_threshold || SLOW_THRESHOLDS[:slow]
+        Minitest::Heat.configuration.slow_threshold
       end
 
       # The number, in seconds, for a test to be considered "painfully slow"
       #
       # @return [Float] number of seconds after which a test is considered painfully slow
       def painfully_slow_threshold
-        Minitest::Heat.configuration.painfully_slow_threshold || SLOW_THRESHOLDS[:painful]
+        Minitest::Heat.configuration.painfully_slow_threshold
       end
 
       # Determines if a test should be considered slow by comparing it to the low end definition of
@@ -200,7 +200,41 @@ module Minitest
       #
       # @return [String] the first line of the exception message
       def first_line_of_exception_message
-        message.split("\n")[0]
+        return '' if message.nil? || message.empty?
+
+        text = message.split("\n")[0].to_s
+
+        text.size > exception_message_limit ? "#{text[0..exception_message_limit]}..." : text
+      end
+
+      def exception_message_limit
+        200
+      end
+
+      # Generates a hash representation for JSON serialization
+      #
+      # @return [Hash] issue data
+      def to_h
+        {
+          type: type,
+          test_class: test_class,
+          test_name: test_identifier,
+          execution_time: execution_time,
+          assertions: assertions,
+          message: message,
+          test_location: locations.test_definition&.to_h,
+          failure_location: failure_location_hash
+        }
+      end
+
+      private
+
+      def failure_location_hash
+        location = locations.most_relevant
+        return nil if location.nil?
+        return nil if location == locations.test_definition
+
+        location.to_h
       end
     end
   end

data/lib/minitest/heat/location.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'pathname'
+
 module Minitest
   module Heat
     # Consistent structure for extracting information about a given location. In addition to the
@@ -42,6 +44,17 @@ module Minitest
         ]
       end
 
+      # Generates a hash representation for JSON serialization
+      #
+      # @return [Hash] location data with file, line, and container
+      def to_h
+        {
+          file: relative_filename,
+          line: line_number,
+          container: container
+        }
+      end
+
       # A short relative pathname and line number pair
       #
       # @return [String] the short filename/line number combo. ex. `dir/file.rb:23`
@@ -133,7 +146,7 @@ module Minitest
       #
       # @return [Boolean] true if the file is in the project (source code or test) but not vendored
       def project_file?
-        path.include?(project_root_dir) && !bundled_file?
+        path.include?(project_root_dir) && !bundled_file? && !binstub_file?
       end
 
       # Determines if the file is in the project `vendor/bundle` directory.
@@ -143,6 +156,15 @@ module Minitest
         path.include?("#{project_root_dir}/vendor/bundle")
       end
 
+      # Determines if the file is in the project `bin` directory. With binstub'd gems, they'll
+      #   appear to be source code because the code is located in the project directory. This helps
+      #   make sure the backtraces don't think that's the case
+      #
+      # @return [Boolean] true if the file is in `<project_root>/bin
+      def binstub_file?
+        path.include?("#{project_root_dir}/bin")
+      end
+
       # Determines if a given file follows the standard approaching to naming test files.
       #
       # @return [Boolean] true if the file name starts with `test_` or ends with `_test.rb`
@@ -154,7 +176,7 @@ module Minitest
       #
       # @return [Boolean] true if the file is in the project but not a test file or vendored file
       def source_code_file?
-        project_file? && !test_file? && !bundled_file?
+        project_file? && !test_file?
       end
 
       # A safe interface to getting the last modified time for the file in question

data/lib/minitest/heat/map.rb

@@ -30,6 +30,13 @@ module Minitest
         hot_files.take(MAXIMUM_FILES_TO_SHOW)
       end
 
+      # Generates a hash representation for JSON serialization
+      #
+      # @return [Array<Hash>] array of hit hashes sorted by weight (highest first)
+      def to_h
+        hot_files.map(&:to_h)
+      end
+
       private
 
       # Sorts the files by hit "weight" so that the most problematic files are at the beginning

data/lib/minitest/heat/output/backtrace.rb

@@ -5,7 +5,6 @@ module Minitest
     class Output
       # Builds the collection of tokens for displaying a backtrace when an exception occurs
       class Backtrace
-        DEFAULT_LINE_COUNT = 10
         DEFAULT_INDENTATION_SPACES = 2
 
         attr_accessor :locations, :backtrace
@@ -25,14 +24,14 @@ module Minitest
         #
         # @return [Integer] the number of lines to limit the backtrace to
         def line_count
-          # Defined as a method instead of using the constant directlyr in order to easily support
+          # Defined as a method instead of using the constant directly in order to easily support
           # adding options for controlling how many lines are displayed from a backtrace.
           #
           # For example, instead of a fixed number, the backtrace could dynamically calculate how
           # many lines it should displaye in order to get to the origination point. Or it could have
           # a default, but inteligently go back further if the backtrace meets some criteria for
           # displaying more lines.
-          DEFAULT_LINE_COUNT
+          ::Minitest::Heat::Backtrace::LineCount.new(backtrace.locations).limit
         end
 
         # A subset of parsed lines from the backtrace.
@@ -49,7 +48,7 @@ module Minitest
           #   it could display the entire backtrace without filtering anything.
           # - It could scan the backtrace to the first appearance of project files and then display
           #   all of the lines that occurred after that instance
-          # - It coudl filter the lines differently whether the issue originated from a test or from
+          # - It could filter the lines differently whether the issue originated from a test or from
           #   the source code.
           # - It could allow supporting a "compact" or "robust" reporter style so that someone on
           #   a smaller screen could easily reduce the information shown so that the results could
@@ -122,7 +121,8 @@ module Minitest
         def source_code_line_token(location)
           return nil unless location.project_file?
 
-          [:muted, " #{Output::SYMBOLS[:arrow]} `#{location.source_code.line.strip}`"]
+          source_line = location.source_code.line
+          [:muted, " #{Output::SYMBOLS[:arrow]} `#{source_line&.strip || '(source unavailable)'}`"]
         end
 
         def containining_element_token(location)