flutter 0.1.0.pre.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c941483caa54c2444a2cfb3f264f9cea9cf79dbbeaac3e70803f83929d5ca542
-  data.tar.gz: 942bf3843ba7de39bd80c32b69f045126cc08a8b1a3a7b7d139d992a2642438a
+  metadata.gz: 2ca2f5eb98359bf0cbac8abbdedcbe6ca27ec7bf205625f44cf0c4150313eeb4
+  data.tar.gz: 6620320c3c54d63117ddc95550c0d4223411bfe9b6b469336fe9f60ffcddcfe3
 SHA512:
-  metadata.gz: a2a7862c51c5ecc07bc8ac6a16f99ab5e324a76a8905eab1382369c3e8f0230b1e062e774ad7934f526351c630ad4428478b66759ca68b9d5037d050df07b521
-  data.tar.gz: 43ea7ed0cbfcbbc354f1a1d7816d4bae213b73acdf9bb9585eeafbab545396f45d7eeb6adaa9aa8f8c085fcb7717f15c579d2f0a60804aed356df2e244c64ab9
+  metadata.gz: 6f97e5720ea6fd890e4c6283a1193750eea3c1ffa64de2de550793cecb14f8636a205774a08811a3f4aea35ed5a764023603fa91a33bd0b4d00496925f4ab35c
+  data.tar.gz: 7f890be9219df6f89fde38e9bc34479a65c9a3d8d910ec1495732a2a32ac65d33291c507b8e7b6950facca0d02b6a47c726c864ae2abde9a4416ae983096b29c

data/CHANGELOG.md

@@ -1,6 +1,30 @@
-## [Unreleased]
-## [0.1.0.pre.2]
-- Initial release
-  - Minitest integration
-  - RSpec integration
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+## 0.2.0
+### Added
+- CI Recipe in README
+- CI integration for incremental tests in branches/pull requests
+- Release workflow tasks & github actions integration
+
+### Fixed
+- Ensure all methods (including inherited ones) are considered when calculating signatures for a class or module.
+- Fix calculation of total / filtered examples for rspec integration
+
+## 0.1.0.pre.3
+### Added
+- Improved documentation for Persistence classes
+- Improved documentation for Tracker
+
+### Changed
+- Pinned dependencies to known working minimum versions
+
+## 0.1.0.pre.2
+### Added
+- Minitest integration
+- RSpec integration
 

data/Gemfile

@@ -11,6 +11,7 @@ group :test, :development do
   gem "overcommit", "~> 0.59.1"
   gem "gem-release", "~> 2.2"
   gem "guard", "~> 2.18"
+  gem "keepachangelog", "~> 0.6.1"
   gem "rubocop", "~> 1.21"
   gem "rubocop-shopify", require: false
   gem "rubocop-minitest", "~> 0.22.1"

data/README.md

@@ -107,7 +107,55 @@ guard :rspec, cmd: "rspec" do
 end
 ```
 ## Configuring flutter in continuous integration
-**TODO**
+
+Flutter can be used in continuous integration environments to speed up the turn
+around time from running tests by only running tests affected by the changes
+in a pull request.
+
+### Github Actions
+The following example workflow with github actions does the following:
+- Always run all tests on the `main` branch
+- Only run tests affected by the "current" commit for CI workflows triggered by a `push` event on other branches
+- If the CI workflow is triggered due to a `pull_request` event, run all tests affected by all commits in the branch
+  (by comparing against the branch point of the pull request)
+
+```yaml
+    # Get the commit where this branch diverges from origin/main
+    - name: Retrieve branch point
+      if: github.event_name == 'pull_request'
+      run: |
+        echo "::set-output name=KEY::$(diff -u <(git rev-list --first-parent origin/main) <(git rev-list --first-parent HEAD) | sed -ne 's/^ //p' | head -1)"
+      id: cache_keys
+    # Use the always-upload-cache action to:
+    #  - Restore the flutter state from cache from either the branch point (if it was set in the previous step)
+    #    or the last run in the current branch
+    #  - After the run cache the flutter state using the current commit hash as the hash key
+    - name: Setup flutter state
+      id: flutter-state
+      uses: pat-s/always-upload-cache@v2.1.5
+      env:
+        cache-name: cache-flutter-state
+      with:
+        path: .flutter
+        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ matrix.ruby-version }}-${{ github.sha }}
+        restore-keys: |
+          ${{ runner.os }}-build-${{ env.cache-name }}-${{ matrix.ruby-version }}-${{ steps.cache_keys.outputs.KEY }}
+    # If this is a push event on the main branch, clear the flutter state
+    # so that all tests are run and a full state is cached on the main branch
+    - name: Clear flutter state
+      if: github.event_name == 'push' && startsWith(github.ref, 'refs/heads/main')
+      run: rm -rf .flutter
+```
+> **Note**
+> The exact CI configuration would ofcourse depend on your workflow and confidence in selectively
+> running tests for pull requests.
+
+> **Warning**
+> Selectively running tests in a pull request would show a drop in coverage if you are collecting
+> and/or using code coverage as a "Check". One way to make Flutter work hand in hand with code
+> coverage checks is to only validate that the diff in the pull request has a 100% coverage. For
+> example with [codecov](https://docs.codecov.com/docs/commit-status#section-project-status) this can be
+> achieved by only enabling the `project` status for the main branch and `patch` status otherwise.
 
 ## Related work
 
@@ -119,7 +167,19 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 This project uses [overcommit](https://github.com/sds/overcommit) to enforce standards. Enable the precommit hooks in your local checkout by running: `overcommit --sign`
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Releasing a new version
+- Ensure that the [Unreleased](./CHANGELOG.md#Unreleased) section of the changelog is up to date
+  and contains useful details.
+- Create a new release using the `release` rake task as follows (for more details about specifying the version change
+  run `gem bump --help` which is the command used by the task):
+  - Patch release `bundle exec rake release["-v patch"]`
+  - Minor release `bundle exec rake release["-v minor"]`
+  - Major release `bundle exec rake release["-v major"]`
+  > **Note**
+  > The `release` rake task automates updating the changelog & version, committing the changes & creating a new tag
+- Push the tag. The CI workflow for tag pushes will take care of publishing the gem & creating a github release.
 
 ## Contributing
 

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
 require "rake/testtask"
+require "keepachangelog"
 
 Rake::TestTask.new(:unit) do |t|
   t.libs << "test"
@@ -22,3 +22,37 @@ RSpec::Core::RakeTask.new(:spec)
 
 task test: [:unit, :spec]
 task default: [:test, :spec, "rubocop:autocorrect_all"]
+
+desc "Increment the version, update changelog and create a tag for the release"
+task :release, [:version] do |_t, args|
+  parser = Keepachangelog::MarkdownParser.load("CHANGELOG.md")
+  log = parser.parsed_content["versions"].delete("Unreleased")
+  sh("gem bump --pretend #{args[:version]}") do |ok, _|
+    if ok
+      new_version = %x(gem bump --no-commit #{args[:version]} | awk '{print $4}' | uniq).chomp
+      parser.parsed_content["versions"]["Unreleased"] = { "url" => nil, "date" => nil, "changes" => {} }
+      parser.parsed_content["versions"][new_version] = log
+      File.open("CHANGELOG.md", "w") do |file|
+        file.write(parser.to_md)
+      end
+      %x(git add CHANGELOG.md lib/flutter/version.rb)
+      %x(git commit -m "Bump flutter to #{new_version}")
+      %x(gem tag -s)
+      Rake::Task["release_notes"].execute({ version: new_version })
+    end
+  end
+end
+
+desc "Get release notes for the current or specific version"
+task :release_notes, [:version] do |_t, args|
+  version = (args[:version] || Flutter::VERSION)
+  parser = Keepachangelog::MarkdownParser.load("CHANGELOG.md")
+  parser.parsed_content.delete("intro")
+  parser.parsed_content.delete("title")
+  parser.parsed_content["versions"] = parser.parsed_content["versions"].select { |k, _v| k == version }
+  lines = parser.to_md.split("\n")
+  chunk = ["## #{version}"] + (
+    lines.slice_after { |line| line.include?("## #{version}") }.to_a[1] || []
+  )
+  puts chunk.join("\n")
+end

data/codecov.yml

@@ -0,0 +1,13 @@
+coverage:
+  status:
+    project:
+      default:
+        paths:
+          - "lib"
+        branches:
+          - main
+    patch:
+      default:
+        paths:
+          - "lib"
+        informational: false

data/lib/flutter/minitest.rb

@@ -10,7 +10,7 @@ end
 module Flutter
   module Minitest
     class << self
-      attr_accessor :filtered
+      attr_accessor :filtered, :total
 
       def flutter_tracker
         @tracker ||= Flutter::Tracker.new(
@@ -31,7 +31,7 @@ module Flutter
           return unless ::Flutter.enabled
 
           Flutter::Minitest.flutter_tracker.persist!
-          $stdout.puts "Flutter filtered out #{Flutter::Minitest.filtered} tests"
+          $stdout.puts "Flutter filtered #{Flutter::Minitest.filtered} / #{Flutter::Minitest.total} tests"
           if @verbose
             $stdout.puts "Persisted flutter #{Flutter::Minitest.flutter_tracker}"
           end
@@ -43,17 +43,15 @@ module Flutter
       module ClassMethods
         def runnable_methods
           Flutter::Minitest.filtered ||= 0
+          Flutter::Minitest.total ||= 0
           default = super()
+          Flutter::Minitest.total += default.length
           default.select do |test|
-            skip = Minitest.flutter_tracker.skip?(
+            !Minitest.flutter_tracker.skip?(
               "#{name}##{test}",
               File.absolute_path(instance_method(test).source_location[0]),
               instance_method(test).source,
-            )
-            if skip
-              Flutter::Minitest.filtered += 1
-            end
-            !skip
+            ).tap { |skip| Flutter::Minitest.filtered += 1 if skip }
           end
         end
       end

data/lib/flutter/parser.rb

@@ -8,6 +8,11 @@ module Flutter
   class Parser
     attr_reader :signatures
 
+    @method_cache = {}
+    class << self
+      attr_reader :method_cache
+    end
+
     def initialize(file)
       @signatures = {}
       @targets = Set.new
@@ -49,23 +54,17 @@ module Flutter
       require_relative @file
       @targets.each do |container|
         instance = Kernel.const_get(container)
-        class_methods = (
-          instance.methods - Object.methods
-        ) + (
-          instance.private_methods - Object.private_methods
-        )
-        instance_methods = (
-          instance.instance_methods - Object.instance_methods
-        ) + (
-          instance.private_instance_methods - Object.private_instance_methods
-        )
+        class_methods = instance.methods + instance.private_methods
+        instance_methods = instance.instance_methods + instance.private_instance_methods
 
         @signatures.merge!(class_methods.map do |method|
-          ["#{container}::#{method}", source_hash(instance.method(method))]
-        end.to_h)
+          hash = source_hash(instance.method(method))
+          ["#{container}::#{method}", hash] if hash
+        end.compact.to_h)
         @signatures.merge!(instance_methods.map do |method|
-          ["#{container}:#{method}", source_hash(instance.instance_method(method))]
-        end.to_h)
+          hash = source_hash(instance.instance_method(method))
+          ["#{container}:#{method}", hash] if hash
+        end.compact.to_h)
       rescue NameError
         $stderr.puts "failed to load #{container} in #{@file}"
       end
@@ -74,9 +73,12 @@ module Flutter
     end
 
     def source_hash(callable)
-      Digest::SHA1.hexdigest(callable.source)
+      return unless callable.source_location
+
+      sep = callable.is_a?(UnboundMethod) ? ":" : "::"
+      Parser.method_cache["#{callable.owner}#{sep}#{callable.name}"] ||= Digest::SHA1.hexdigest(callable.source)
     rescue MethodSource::SourceNotFoundError
-      "<no-source>"
+      nil
     end
   end
 end

data/lib/flutter/persistence.rb

@@ -4,40 +4,68 @@ require "fileutils"
 require "set"
 module Flutter
   module Persistence
+    # The abstract base storage.
+    #
+    # To implement a custom storage, override the following methods:
+    # * {#test_mapping}
+    # * {#source_mapping}
+    # * {#update_test_mapping!}
+    # * {#update_source_mapping!}
+    # * {#load!}
+    # * {#persist!}
+    # * {#clear!}
+    #
+    # @abstract Override this class to implement a custom storage
     class AbstractStorage
       def initialize
         load!
       end
 
       # :nocov:
+
+      # Mapping of +test_id -> source file -> callable_id+
+      # @return [Hash<String, Hash<String, Set<String>>>]
       def test_mapping
         raise NotImplementedError
       end
 
+      # Mapping of +source file -> callable_id -> signature+
+      # @return [Hash<String, Hash<String, String>>] mapping
       def source_mapping
         raise NotImplementedError
       end
 
+      ##
+      # Update {#test_mapping}
+      #
+      # @param [Hash<String, Hash<String, String>>] mapping
       def update_test_mapping!(mapping)
         raise NotImplementedError
       end
 
+      ##
+      # Update {#source_mapping}
+      #
+      # @param [Hash<String, Hash<String, String>>] mapping
       def update_source_mapping!(mapping)
         raise NotImplementedError
       end
 
-      def persist!(updates)
-        raise NotImplementedError
-      end
-
-      def to_s
+      # Save the state of test & source mapping to the underlying
+      # storage
+      # @return [void]
+      def persist!
         raise NotImplementedError
       end
 
+      # Clear any saved state in the underlying storage
+      # @return [void]
       def clear!
         raise NotImplementedError
       end
 
+      # If the storage was already persisted load the current state
+      # @return [void]
       def load!
         raise NotImplementedError
       end
@@ -48,6 +76,8 @@ module Flutter
       require "yaml"
       # ruby >= 3.1 requires this
       YAML_LOAD_OPTS = RUBY_VERSION > "3.1" ? { permitted_classes: [Hash, Set, Symbol] } : {}
+
+      # @param [String] path The directory to store the +state.yml+ file
       def initialize(path:)
         @path = File.absolute_path(path)
         @full_path = File.join(@path, "state.yml")
@@ -55,6 +85,7 @@ module Flutter
         super()
       end
 
+      # (see AbstractStorage#load!)
       def load!
         if File.exist?(@full_path)
           persisted = YAML.load(File.read(@full_path), **YAML_LOAD_OPTS)
@@ -62,27 +93,33 @@ module Flutter
         end
       end
 
+      # (see AbstractStorage#test_mapping)
       def test_mapping
         @state.fetch(:test_mapping) { @state[:test_mapping] = {} }
       end
 
+      # (see AbstractStorage#source_mapping)
       def source_mapping
         @state.fetch(:source_mapping) { @state[:source_mapping] = {} }
       end
 
+      # (see AbstractStorage#update_test_mapping!)
       def update_test_mapping!(mapping)
         test_mapping.merge!(mapping)
       end
 
+      # (see AbstractStorage#update_source_mapping!)
       def update_source_mapping!(mapping)
         source_mapping.merge!(mapping)
       end
 
+      # (see AbstractStorage#clear!)
       def clear!
         FileUtils.rm(@full_path) if File.exist?(@full_path)
         @state.clear
       end
 
+      # (see AbstractStorage#persist!)
       def persist!
         FileUtils.mkdir_p(@path) unless File.exist?(@path)
         File.open(@full_path, "w") { |file| file.write(@state.to_yaml) }
@@ -95,6 +132,7 @@ module Flutter
 
     class Marshal < AbstractStorage
       require "pstore"
+      # @param [String] path The directory to store the marshaled state file +state.pstore+
       def initialize(path:)
         @path = File.absolute_path(path)
         FileUtils.mkdir_p(@path) unless File.exist?(@path)
@@ -103,6 +141,7 @@ module Flutter
         super()
       end
 
+      # (see AbstractStorage#load!)
       def load!
         @state = PStore.new(@full_path)
         @state.transaction do
@@ -111,18 +150,21 @@ module Flutter
         end
       end
 
+      # (see AbstractStorage#test_mapping)
       def test_mapping
         @state.transaction do
           return @state[:test_mapping]
         end
       end
 
+      # (see AbstractStorage#source_mapping)
       def source_mapping
         @state.transaction do
           return @state[:source_mapping]
         end
       end
 
+      # (see AbstractStorage#update_test_mapping!)
       def update_test_mapping!(mapping)
         @state.transaction do
           @state[:test_mapping] ||= {}
@@ -130,6 +172,7 @@ module Flutter
         end
       end
 
+      # (see AbstractStorage#update_source_mapping!)
       def update_source_mapping!(mapping)
         @state.transaction do
           @state[:source_mapping] ||= {}
@@ -137,13 +180,16 @@ module Flutter
         end
       end
 
+      # (see AbstractStorage#clear!)
       def clear!
         FileUtils.rm(@full_path) if File.exist?(@full_path)
       end
 
+      # (see AbstractStorage#persist!)
       def persist!
       end
 
+      # @return [String]
       def to_s
         "state: #{@full_path}"
       end

data/lib/flutter/rspec.rb

@@ -5,7 +5,7 @@ require_relative "tracker"
 module Flutter
   module RSpec
     class << self
-      attr_accessor :filtered
+      attr_accessor :filtered, :total
 
       def tracker
         @tracker ||= Flutter::Tracker.new(
@@ -17,20 +17,20 @@ module Flutter
 
     module ClassMethods
       def filtered_examples
-        Flutter::RSpec.filtered ||= 0
+        Flutter::RSpec.filtered ||= Set.new
+        Flutter::RSpec.total ||= Set.new
         Flutter::RSpec.tracker.reset! if Flutter.enabled && Flutter.config.reset_storage
 
         original = super
+        Flutter::RSpec.total.merge(original)
         return original unless Flutter.enabled
 
         original.select do |example|
-          skip = example.metadata[:block] && Flutter::RSpec.tracker.skip?(
+          !(example.metadata[:block] && Flutter::RSpec.tracker.skip?(
             example.full_description,
             example.metadata[:absolute_file_path],
             example.metadata[:block].source,
-          )
-          Flutter::RSpec.filtered += 1 if skip
-          !skip
+          ).tap { |skip| Flutter::RSpec.filtered << example if skip })
         end
       end
     end
@@ -58,7 +58,7 @@ if defined?(RSpec.configure)
     config.after(:suite) do
       if Flutter.enabled
         $stdout.puts
-        $stdout.puts "Flutter filtered out #{Flutter::RSpec.filtered} examples"
+        $stdout.puts "Flutter filtered #{Flutter::RSpec.filtered.length} / #{Flutter::RSpec.total.length} examples"
         Flutter::RSpec.tracker.persist!
       end
     end

data/lib/flutter/tracker.rb

@@ -7,9 +7,20 @@ require_relative "parser"
 require "pry"
 
 module Flutter
+  # @attr [Hash<String, Hash<String, Set<String>>>] test_mapping Mapping of tests to
+  #  files -> callable_ids
+  # @attr [Hash<String, Hash<String, String>>] source_mapping Mapping of
+  #  source files -> callable_id -> signature
+  # @attr [Persistence::AbstractStorage] storage the storage instance used for
+  #  persisting the state of the tracker
   class Tracker
-    attr_reader :test_mapping, :source_mapping
+    attr_reader :test_mapping, :source_mapping, :storage
 
+    # @param [Array<String>] sources
+    # @param [Array<String>] exclusions
+    # @param [Class<Flutter::Persistence::AbstractStorage>] storage_class
+    # @param [Hash] storage_options Additionally options that should be passed
+    #  to the +storage_class+ constructor
     def initialize(sources, exclusions, storage_class, storage_options)
       @sources = sources.map { |s| File.absolute_path(s) }
       @exclusions = exclusions.map { |s| File.absolute_path(s) }
@@ -23,8 +34,8 @@ module Flutter
       @tracked_files = {}
     end
 
-    # Resets the in-memory test_mapping for each test, and stores the methods that
-    # the test calls in the in-memory test_mapping
+    # Starts tracking calls made by +test+
+    # @param [String] test A unique identifier for the test
     def start(test)
       # Delete test from the in-memory mapping to allow each new test run
       # to store all the functions that the test calls into
@@ -35,10 +46,24 @@ module Flutter
       @current_tracepoint&.enable
     end
 
+    # End tracking (should be called after a call to {#start})
     def stop
       @current_tracepoint&.disable
     end
 
+    ##
+    # Decides if a test should be skipped based on *all* of the following
+    # criteria being met:
+    #
+    # 1. Test was seen before
+    # 2. Test sources have not changed since the last time it was executed
+    # 3. All the callables triggered within the scope of this test have no
+    #    changes in their source since the last time this test was executed
+    #
+    # @param [String] test A unique identifier for the test
+    # @param [String] test_location The absolute path to the source file containing the test
+    # @param [String] test_source The source code of the test itself
+    # @return [TrueClass, FalseClass] If the test should be skipped
     def skip?(test, test_location, test_source)
       test_location_rel = relative_path(test_location)
       @test_source_mapping.fetch(test_location_rel) do
@@ -58,13 +83,22 @@ module Flutter
       end.all?
     end
 
+    ##
+    # Persist the state of the tracker to the storage
+    # specified by {#storage}
+    # @return [void]
     def persist!
       @storage.update_test_mapping!(@test_mapping)
       @storage.update_source_mapping!(generate_source_mapping)
       @storage.persist!
     end
 
+    ##
+    # Reset the state of the tracker and the storage
+    # that it was configured with
+    # @return [void]
     def reset!
+      $stdout.puts "Resetting flutter: #{@storage}"
       @storage.clear!
       @source_mapping.clear
       @test_mapping.clear
@@ -74,8 +108,6 @@ module Flutter
       @storage.to_s
     end
 
-    attr_reader :mapping
-
     private
 
     def hit!(test, tracepoint)
@@ -116,6 +148,13 @@ module Flutter
       end
     end
 
+    ##
+    # Check if a file pair should be tracked or not based on the
+    # +sources+ and +exclusions+ lists provided when initializing
+    # the instance
+    #
+    # @param [String] file
+    # @param [Symbol] _method
     def tracked?(file, _method)
       @tracked_files.fetch(file) do
         @sources.any?(->(source) { File.fnmatch?(source, file) }) && !@exclusions.any?(->(exclusion) {
@@ -124,6 +163,10 @@ module Flutter
       end
     end
 
+    ##
+    # Generates a mapping of
+    #
+    # @return [Hash<String, Hash<String, Hash<String, String>>>]
     def generate_source_mapping
       @test_mapping.map { |_k, v| v.keys }.flatten.uniq.map do |file|
         [file, @current_source_mapping.fetch(file) { Flutter::Parser.new(file).signatures }]

data/lib/flutter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Flutter
-  VERSION = "0.1.0.pre.2"
+  VERSION = "0.2.0"
 end