flutter 0.1.0.pre.2 → 0.1.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c941483caa54c2444a2cfb3f264f9cea9cf79dbbeaac3e70803f83929d5ca542
-  data.tar.gz: 942bf3843ba7de39bd80c32b69f045126cc08a8b1a3a7b7d139d992a2642438a
+  metadata.gz: bdffa233de57141c16bbbd41684ca85b04208b32edeec97625662383f4e3e753
+  data.tar.gz: be3eb7f6bb1d0ffd8123ad4b8c2293ecdaf4c3979c75be8471542a2c26e1d771
 SHA512:
-  metadata.gz: a2a7862c51c5ecc07bc8ac6a16f99ab5e324a76a8905eab1382369c3e8f0230b1e062e774ad7934f526351c630ad4428478b66759ca68b9d5037d050df07b521
-  data.tar.gz: 43ea7ed0cbfcbbc354f1a1d7816d4bae213b73acdf9bb9585eeafbab545396f45d7eeb6adaa9aa8f8c085fcb7717f15c579d2f0a60804aed356df2e244c64ab9
+  metadata.gz: e301754a8492f5eaae1ba2388fe39c4d1fe2250b61bb7b792025d646e96719bd1df76a1ed8f669a821107e4e12f54b89c070671f5b86c29d24eae7bf2a3de3d7
+  data.tar.gz: 4e69808a87b89d50f3d7fcf964ae3a2d5ccc176294e7f610e00d5ffb712131384ff24bb64e630e1ef1f5df1afac7f2175c986d031b4ada8dba9af37df00c930d

data/CHANGELOG.md

@@ -1,6 +1,20 @@
+# 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.1.0.pre.3]
+### Added
+  - Improved documentation for Tracker
+  - Improved documentation for Persistance classes
+
+### Changed
+  - Pinned dependencies to known working minimum versions
+
 ## [0.1.0.pre.2]
-- Initial release
+### Added
   - Minitest integration
   - RSpec integration
 

data/README.md

@@ -119,7 +119,9 @@ 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`. To release a new version, update the version number by running `gem bump`,
+then move the `Unreleased` entries in the [CHANGELOG](./CHANGELOG.md) to the new version and commit that.
+Finally tag and release the gem with `gem tag` and `gem release`
 
 ## Contributing
 

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/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,12 +83,20 @@ 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!
       @storage.clear!
       @source_mapping.clear
@@ -74,8 +107,6 @@ module Flutter
       @storage.to_s
     end
 
-    attr_reader :mapping
-
     private
 
     def hit!(test, tracepoint)
@@ -116,6 +147,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 +162,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.1.0.pre.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flutter
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.2
+  version: 0.1.0.pre.3
 platform: ruby
 authors:
 - Ali-Akber Saifee
@@ -9,50 +9,50 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-09-29 00:00:00.000000000 Z
+date: 2022-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: deep_merge
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: dry-configurable
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.15'
 - !ruby/object:Gem::Dependency
   name: parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.1'
 description: "Flutter plugs in to your RSpec or Minitest test suites\n  and helps
   you run only the tests that exercise the code you have changed since the last run\n
   \ "
@@ -73,81 +73,6 @@ files:
 - README.md
 - Rakefile
 - TODO.md
-- integration_tests/minitest/grape_app/.gitignore
-- integration_tests/minitest/grape_app/.ruby-version
-- integration_tests/minitest/grape_app/Gemfile
-- integration_tests/minitest/grape_app/Gemfile.lock
-- integration_tests/minitest/grape_app/README.md
-- integration_tests/minitest/grape_app/Rakefile
-- integration_tests/minitest/grape_app/api/api.rb
-- integration_tests/minitest/grape_app/api/routes/api_helpers.rb
-- integration_tests/minitest/grape_app/api/routes/change_request/api.rb
-- integration_tests/minitest/grape_app/api/routes/change_request/response_entity.rb
-- integration_tests/minitest/grape_app/api/routes/event/api.rb
-- integration_tests/minitest/grape_app/api/routes/event/response_entity.rb
-- integration_tests/minitest/grape_app/api/routes/project/api.rb
-- integration_tests/minitest/grape_app/api/routes/project/response_entity.rb
-- integration_tests/minitest/grape_app/api/routes/property/api.rb
-- integration_tests/minitest/grape_app/api/routes/property/response_entity.rb
-- integration_tests/minitest/grape_app/api/routes/trackable_object/api.rb
-- integration_tests/minitest/grape_app/api/routes/trackable_object/response_entity.rb
-- integration_tests/minitest/grape_app/api/routes/tracking_spec/api.rb
-- integration_tests/minitest/grape_app/api/routes/tracking_spec/response_entity.rb
-- integration_tests/minitest/grape_app/api/routes/tracking_spec/spec_response.rb
-- integration_tests/minitest/grape_app/api/routes/user/api.rb
-- integration_tests/minitest/grape_app/api/routes/user/response_entity.rb
-- integration_tests/minitest/grape_app/app/app.rb
-- integration_tests/minitest/grape_app/app/change_request/endpoint.rb
-- integration_tests/minitest/grape_app/app/change_request/generate_system_changes.rb
-- integration_tests/minitest/grape_app/app/change_request/service.rb
-- integration_tests/minitest/grape_app/app/event/endpoint.rb
-- integration_tests/minitest/grape_app/app/event/service.rb
-- integration_tests/minitest/grape_app/app/event/validator.rb
-- integration_tests/minitest/grape_app/app/project/endpoint.rb
-- integration_tests/minitest/grape_app/app/project/service.rb
-- integration_tests/minitest/grape_app/app/property/endpoint.rb
-- integration_tests/minitest/grape_app/app/property/service.rb
-- integration_tests/minitest/grape_app/app/trackable_object/endpoint.rb
-- integration_tests/minitest/grape_app/app/trackable_object/service.rb
-- integration_tests/minitest/grape_app/app/trackable_object/validator.rb
-- integration_tests/minitest/grape_app/app/tracking_spec/endpoint.rb
-- integration_tests/minitest/grape_app/app/tracking_spec/expand_tracking_spec_events.rb
-- integration_tests/minitest/grape_app/app/tracking_spec/service.rb
-- integration_tests/minitest/grape_app/app/tracking_spec/validator.rb
-- integration_tests/minitest/grape_app/app/utils/errors/api_exceptions.rb
-- integration_tests/minitest/grape_app/app/utils/errors/service_exceptions.rb
-- integration_tests/minitest/grape_app/app/versioned_entity/entity.rb
-- integration_tests/minitest/grape_app/app/versioned_entity/service.rb
-- integration_tests/minitest/grape_app/app/versioned_entity/validator.rb
-- integration_tests/minitest/grape_app/app/versioned_entity_snapshot/entity.rb
-- integration_tests/minitest/grape_app/config.ru
-- integration_tests/minitest/grape_app/config/boot.rb
-- integration_tests/minitest/grape_app/db/proto/change_request.rb
-- integration_tests/minitest/grape_app/db/proto/common/doc.rb
-- integration_tests/minitest/grape_app/db/proto/event.rb
-- integration_tests/minitest/grape_app/db/proto/event_snapshot.rb
-- integration_tests/minitest/grape_app/db/proto/project.rb
-- integration_tests/minitest/grape_app/db/proto/property.rb
-- integration_tests/minitest/grape_app/db/proto/property_snapshot.rb
-- integration_tests/minitest/grape_app/db/proto/trackable_object.rb
-- integration_tests/minitest/grape_app/db/proto/trackable_object_snapshot.rb
-- integration_tests/minitest/grape_app/db/proto/tracking_spec.rb
-- integration_tests/minitest/grape_app/test/api/functional/event_test.rb
-- integration_tests/minitest/grape_app/test/api/functional/property_test.rb
-- integration_tests/minitest/grape_app/test/api/functional/trackable_object_test.rb
-- integration_tests/minitest/grape_app/test/api/functional/tracking_spec_test.rb
-- integration_tests/minitest/grape_app/test/api/functional/user_test.rb
-- integration_tests/minitest/grape_app/test/api/functional/versioned_entity_helper.rb
-- integration_tests/minitest/grape_app/test/fixtures/change_requests.rb
-- integration_tests/minitest/grape_app/test/fixtures/event_snapshots.rb
-- integration_tests/minitest/grape_app/test/fixtures/events.rb
-- integration_tests/minitest/grape_app/test/fixtures/properties.rb
-- integration_tests/minitest/grape_app/test/fixtures/property_snapshots.rb
-- integration_tests/minitest/grape_app/test/fixtures/sample_tracking_spec.json
-- integration_tests/minitest/grape_app/test/fixtures/trackable_objects.rb
-- integration_tests/minitest/grape_app/test/fixtures/trackable_objects_snapshots.rb
-- integration_tests/minitest/grape_app/test/fixtures/tracking_specs.rb
-- integration_tests/minitest/grape_app/test/test_helper.rb
 - lib/flutter.rb
 - lib/flutter/config.rb
 - lib/flutter/minitest.rb
@@ -173,14 +98,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Intelligent test selection based on incremental code changes

data/integration_tests/minitest/grape_app/.gitignore

@@ -1,67 +0,0 @@
-*.gem
-*.rbc
-/.config
-/coverage/
-/InstalledFiles
-/pkg/
-/spec/reports/
-/spec/examples.txt
-/test/tmp/
-/test/version_tmp/
-/tmp/
-
-# Used by dotenv library to load environment variables.
-# .env
-
-# Ignore Byebug command history file.
-.byebug_history
-
-## Specific to RubyMotion:
-.dat*
-.repl_history
-build/
-*.bridgesupport
-build-iPhoneOS/
-build-iPhoneSimulator/
-
-## Specific to RubyMotion (use of CocoaPods):
-#
-# We recommend against adding the Pods directory to your .gitignore. However
-# you should judge for yourself, the pros and cons are mentioned at:
-# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
-#
-# vendor/Pods/
-
-## Documentation cache and generated files:
-/.yardoc/
-/_yardoc/
-/doc/
-/rdoc/
-
-## Environment normalization:
-/.bundle/
-/vendor/bundle
-/lib/bundler/man/
-
-# for a library or gem, you might want to ignore these files since the code is
-# intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
-# .ruby-version
-# .ruby-gemset
-
-# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
-.rvmrc
-
-# Used by RuboCop. Remote config files pulled in from inherit_from directive.
-# .rubocop-https?--*
-
-### VisualStudioCode ###
-.vscode/
-
-### VisualStudioCode Patch ###
-# Ignore all local history of files
-.history
-
-.idea/
-
-# End of https://www.gitignore.io/api/visualstudiocode

data/integration_tests/minitest/grape_app/.ruby-version

@@ -1 +0,0 @@
-2.7.1

data/integration_tests/minitest/grape_app/Gemfile

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-source 'https://rubygems.org'
-gem 'dotenv'
-# api definitions
-gem 'grape'
-gem 'grape-entity'
-gem 'grape-swagger'
-# web server
-gem 'puma'
-# task runner for ruby
-gem 'rake'
-gem 'flutter', path: '../../../'
-
-group :development, :test do
-  gem 'minitest' #, require: false
-  gem 'rack-test', require: 'rack/test'
-end