minitest-heat 1.2.0 → 2.0.0

data/RELEASING.md

@@ -0,0 +1,190 @@
+# 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.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

@@ -19,15 +19,18 @@ module Minitest
         end
 
         def max_location
-          locations.size - 1
+          [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,
+            DEFAULT_LINE_COUNT - 1,
             earliest_project_location,
             max_location
-          ].compact.min
+          ].compact.min + 1
         end
       end
     end

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

@@ -10,7 +10,9 @@ 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(':')
+          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(

data/lib/minitest/heat/backtrace.rb

@@ -31,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/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

@@ -200,7 +200,9 @@ module Minitest
       #
       # @return [String] the first line of the exception message
       def first_line_of_exception_message
-        text = 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
@@ -208,6 +210,32 @@ module Minitest
       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
 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`

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

@@ -121,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)

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

@@ -69,7 +69,9 @@ module Minitest
         # @return [String] the cleaned up version of the test name
         def test_name(issue)
           test_prefix = 'test_'
-          identifier = issue.test_identifier
+          identifier = issue.test_identifier.to_s
+
+          return 'Unknown test' if identifier.empty?
 
           if identifier.start_with?(test_prefix)
             identifier.delete_prefix(test_prefix).gsub('_', ' ').capitalize
@@ -87,22 +89,24 @@ module Minitest
         end
 
         def test_location_tokens
+          source_line = locations.test_failure.source_code.line
           [
             [:default, locations.test_definition.relative_filename],
             [:muted, ':'],
             [:default, locations.test_definition.line_number],
             arrow_token,
             [:default, locations.test_failure.line_number],
-            [:muted, "\n  #{locations.test_failure.source_code.line.strip}"]
+            [:muted, "\n  #{source_line&.strip || '(source unavailable)'}"]
           ]
         end
 
         def location_tokens
+          source_line = locations.most_relevant.source_code.line
           [
             [:default, locations.most_relevant.relative_filename],
             [:muted, ':'],
             [:default, locations.most_relevant.line_number],
-            [:muted, "\n  #{locations.most_relevant.source_code.line.strip}"]
+            [:muted, "\n  #{source_line&.strip || '(source unavailable)'}"]
           ]
         end
 
@@ -110,12 +114,15 @@ module Minitest
           filename    = locations.project.filename
           line_number = locations.project.line_number
           source = Minitest::Heat::Source.new(filename, line_number: line_number)
+          source_line = source.line
 
-          [[:muted, " #{Output::SYMBOLS[:arrow]} `#{source.line.strip}`"]]
+          [[:muted, " #{Output::SYMBOLS[:arrow]} `#{source_line&.strip || '(source unavailable)'}`"]]
         end
 
         def summary_tokens
-          [[:italicized, issue.summary.delete_suffix('---------------').strip]]
+          summary_text = issue.summary.to_s
+          cleaned = summary_text.delete_suffix('---------------').strip
+          [[:italicized, cleaned.empty? ? '(no details available)' : cleaned]]
         end
 
         def slowness_summary_tokens

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

@@ -9,7 +9,12 @@ module Minitest
 
         attr_accessor :results, :timer
 
-        def_delegators :@results, :issues, :errors, :brokens, :failures, :skips, :painfuls, :slows, :problems?
+        # Explicitly define issues to avoid Forwardable warning about Object#issues private method
+        def issues
+          @results.issues
+        end
+
+        def_delegators :@results, :errors, :brokens, :failures, :skips, :painfuls, :slows, :problems?
 
         def initialize(results, timer)
           @results = results

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

@@ -17,10 +17,10 @@ module Minitest
           failure: %i[default red],
           skipped: %i[default yellow],
           warning_light: %i[light yellow],
-          italicized: %i[italic gray],
+          italicized: %i[italic default],
           bold: %i[bold default],
           default: %i[default default],
-          muted: %i[light gray]
+          muted: %i[light default]
         }.freeze
 
         attr_accessor :style_key, :content

data/lib/minitest/heat/output.rb

@@ -154,8 +154,9 @@ module Minitest
           tokens.each do |token|
             begin
               print Token.new(*token).to_s(token_format)
-            rescue
-              puts token.inspect
+            rescue ArgumentError => e
+              # Token format error - output debug info and continue
+              puts "Token error (#{e.message}): #{token.inspect}"
             end
           end
           newline

data/lib/minitest/heat/results.rb

@@ -35,15 +35,15 @@ module Minitest
         # numbers if the tests reference a shared method with an assertion in it. So in those cases,
         # the backtrace is simply the test definition
         backtrace = if issue.error?
-          # With errors, we have a backtrace
-          issue.locations.backtrace.project_locations
-        else
-          # With failures, the test definition is the most granular backtrace equivalent
-          location = issue.locations.test_definition
-          location.raw_container = issue.test_identifier
+                      # With errors, we have a backtrace
+                      issue.locations.backtrace.project_locations
+                    else
+                      # With failures, the test definition is the most granular backtrace equivalent
+                      location = issue.locations.test_definition
+                      location.raw_container = issue.test_identifier
 
-          [location]
-        end
+                      [location]
+                    end
 
         @heat_map.add(pathname, line_number, issue.type, backtrace: backtrace)
       end
@@ -76,6 +76,39 @@ module Minitest
         @slows ||= select_issues(:slow).sort_by(&:execution_time).reverse
       end
 
+      # Returns count statistics by issue type
+      #
+      # @return [Hash] counts for each issue type
+      def statistics
+        {
+          total: issues.size,
+          errors: errors.size,
+          broken: brokens.size,
+          failures: failures.size,
+          skipped: skips.size,
+          painful: painfuls.size,
+          slow: slows.size
+        }
+      end
+
+      # Returns all issues that are not successes
+      #
+      # @return [Array<Issue>] issues that represent problems (errors, failures, skips, slow)
+      def issues_with_problems
+        issues.select(&:hit?)
+      end
+
+      # Generates a hash representation for JSON serialization
+      #
+      # @return [Hash] results data
+      def to_h
+        {
+          statistics: statistics,
+          heat_map: heat_map.to_h,
+          issues: issues_with_problems.map(&:to_h)
+        }
+      end
+
       private
 
       def select_issues(issue_type)