leftovers 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98a1dcd328efccf139ec0cfb56a81d5a723b8a6ba62bfd0b522466aa4f8e0a82
-  data.tar.gz: 906c53f6e6963692846639df0619c694e65c9410abc75db6dc3f5a519a2e57d0
+  metadata.gz: aa735d4aa3320b0225d0d256c296b5b3b284593f285d1257a4b8e6bd74a0dd74
+  data.tar.gz: ebaaa2f4c2e93780788e36d961a623a015b1f8d11c0a9799882e5a21a45552f4
 SHA512:
-  metadata.gz: 2ba271c0482aca8feeb1d30e4359b262ecff4f626737ac31b3ca445b0884e52815dbffcac0967b72a903597ea530307abb00ac40fab8b40487f7fdcf0f1b2571
-  data.tar.gz: 0b59bfb6cbfb399be40fa10ebc2c66b5633f5a4ba55da1397010e4d0e577540eff7b9e5c7ddae296fea2def2b99d2449168ef3b91cb165b9ff67d433fb43ec83
+  metadata.gz: 88cf80851cdb71a94a3d5497fa80ab4b020447e6aa23b1a9074ef19789bcdc77b576275aad066ac23170b1d2d18687f0b07322b24792cd31a163f2e70f3d637e
+  data.tar.gz: '0167915df5ad01dcf2368e72a98171cad57b22e4df7d6c8e5bc29b1e8e053b8a9e522746836102d769ca80745105021bbeb297d038ab8cd58410a2d797c34d04'

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# v0.4.3
+- add --write-todo so you can add this to your project without
+immediately fixing everything.
+
 # v0.4.2
 - Make sorbet happy with this as a dependency
 # v0.4.1

data/README.md

@@ -56,8 +56,38 @@ lib/hello_world.rb:18:6 another_tested_unused_method def another_tested_unused_m
 Not directly called at all:
 lib/hello_world.rb:6:6 generated_method= attr_accessor :generated_method
 lib/hello_world.rb:6:6 generated_method attr_accessor :generated_method
+
+how to resolve: https://github.com/robotdana/leftovers/tree/main/Readme.md#how_to_resolve
 ```
 
+if there is an overwhelming number of results, try using [`--write-todo`](#write-todo)
+
+## How to resolve
+
+When running `leftovers` you'll be given a list of method, constant, and variable definitions it thinks are unused. Now what?
+
+they were unintentionally left when removing their calls:
+  - remove their definitions. (they're still there in your git etc history if you want them back)
+
+they are called dynamically:
+  - define how they're called dynamically in the [.leftovers.yml](#configuration-file); or
+  - mark the calls with [`# leftovers:call my_unused_method`](#leftovers-call); or
+  - mark the definition with [`# leftovers:keep`](#leftovers-keep)
+
+they're defined intentionally to only be used by tests:
+  - add [`# leftovers:test_only`](#leftovers-test-only)
+
+they're from a file that shouldn't be checked by leftovers:
+  - add the paths to the [`exclude_paths:`](https://github.com/robotdana/leftovers/tree/main/docs/Configuration.md#exclude_paths) list in the [.leftovers.yml](#configuration-file) file
+
+if there are too many to address when first adding leftovers to your project, try running [`leftovers --write-todo`](#write-todo),
+
+### --write-todo
+
+running `leftovers --write-todo` will generate a supplemental configuration file allowing all the currently detected uncalled definitions, which will be read on subsequent runs of `leftovers` without alerting any of the items mentioned in it.
+
+commit this file so you/your team can gradually address these items while still having leftovers alert you to any newly unused items.
+
 ## Magic comments
 
 ### `# leftovers:keep`

data/leftovers.gemspec

@@ -42,6 +42,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-rspec', '~> 1.44.1'
   spec.add_development_dependency 'simplecov', '>= 0.18.5'
   spec.add_development_dependency 'simplecov-console'
+  spec.add_development_dependency 'timecop'
   spec.add_development_dependency 'tty_string', '>= 0.2.1'
 
   spec.add_development_dependency 'spellr', '>= 0.8.1'

data/lib/leftovers.rb

@@ -26,14 +26,14 @@ module Leftovers # rubocop:disable Metrics/ModuleLength
   autoload(:ProcessorBuilders, "#{__dir__}/leftovers/processor_builders")
   autoload(:RakeTask, "#{__dir__}/leftovers/rake_task")
   autoload(:Reporter, "#{__dir__}/leftovers/reporter")
+  autoload(:TodoReporter, "#{__dir__}/leftovers/todo_reporter")
   autoload(:DynamicProcessors, "#{__dir__}/leftovers/dynamic_processors")
   autoload(:ValueProcessors, "#{__dir__}/leftovers/value_processors")
   autoload(:VERSION, "#{__dir__}/leftovers/version")
 
   class << self
-    attr_accessor :parallel, :progress
+    attr_accessor :parallel, :progress, :reporter
     alias_method :parallel?, :parallel
-
     alias_method :progress?, :progress
   end
 
@@ -64,10 +64,10 @@ module Leftovers # rubocop:disable Metrics/ModuleLength
     end
   end
 
-  def run(stdout: StringIO.new, stderr: StringIO.new) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+  def run(stdout: StringIO.new, stderr: StringIO.new) # rubocop:disable Metrics/MethodLength
     @stdout = stdout
     @stderr = stderr
-    return 0 if leftovers.empty?
+    return reporter.report_success if leftovers.empty?
 
     only_test = []
     none = []
@@ -79,17 +79,7 @@ module Leftovers # rubocop:disable Metrics/ModuleLength
       end
     end
 
-    unless only_test.empty?
-      puts "\e[31mOnly directly called in tests:\e[0m"
-      only_test.each { |definition| reporter.call(definition) }
-    end
-
-    unless none.empty?
-      puts "\e[31mNot directly called at all:\e[0m"
-      none.each { |definition| reporter.call(definition) }
-    end
-
-    1
+    reporter.report(only_test: only_test, none: none)
   end
 
   def reset # rubocop:disable Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
@@ -104,6 +94,10 @@ module Leftovers # rubocop:disable Metrics/ModuleLength
     remove_instance_variable(:@pwd) if defined?(@pwd)
   end
 
+  def resolution_instructions_link
+    "https://github.com/robotdana/leftovers/tree/v#{Leftovers::VERSION}/README.md#how_to_resolve"
+  end
+
   def warn(message)
     stderr.puts("\e[2K#{message}")
   end

data/lib/leftovers/cli.rb

@@ -28,20 +28,29 @@ module Leftovers
       Leftovers.progress = true
 
       opts.banner = 'Usage: leftovers [options]'
+
       opts.on('--[no-]parallel', 'Run in parallel or not, default --parallel') do |p|
         Leftovers.parallel = p
       end
+
       opts.on('--[no-]progress', 'Show progress counts or not, default --progress') do |p|
         Leftovers.progress = p
       end
-      opts.on('-v', '--version', 'Returns the current version') do
-        stdout.puts(Leftovers::VERSION)
-        Leftovers.exit
-      end
+
       opts.on('--dry-run', 'Output files that will be looked at') do
         Leftovers::FileList.new.each { |f| stdout.puts f.relative_path }
         Leftovers.exit
       end
+
+      opts.on('--write-todo', 'Outputs the unused items in a todo file to gradually fix') do
+        Leftovers.reporter = Leftovers::TodoReporter.new
+      end
+
+      opts.on('-v', '--version', 'Returns the current version') do
+        stdout.puts(Leftovers::VERSION)
+        Leftovers.exit
+      end
+
       opts.on('-h', '--help', 'Shows this message') do
         stdout.puts(opts.help)
         Leftovers.exit

data/lib/leftovers/collector.rb

@@ -18,6 +18,7 @@ module Leftovers
     end
 
     def collect
+      Leftovers.reporter.prepare
       collect_file_list(Leftovers::FileList.new)
       print_progress
       Leftovers.newline

data/lib/leftovers/definition.rb

@@ -2,7 +2,7 @@
 
 module Leftovers
   class Definition
-    attr_reader :name, :test, :location_s
+    attr_reader :name, :test, :location_s, :source_line
     alias_method :names, :name
 
     alias_method :test?, :test
@@ -14,7 +14,7 @@ module Leftovers
     )
       @name = name
       @path = location.source_buffer.name.to_s
-      @location_source_line = location.source_line.to_s
+      @source_line = location.source_line.to_s
       @location_column_range_begin = location.column_range.begin.to_i
       @location_column_range_end = location.column_range.end.to_i
       @location_source = location.source.to_s
@@ -29,9 +29,9 @@ module Leftovers
     end
 
     def highlighted_source(highlight = "\e[31m", normal = "\e[0m")
-      @location_source_line[0...@location_column_range_begin].lstrip +
+      @source_line[0...@location_column_range_begin].lstrip +
         highlight + @location_source + normal +
-        @location_source_line[@location_column_range_end..-1].rstrip
+        @source_line[@location_column_range_end..-1].rstrip
     end
 
     def in_collection?

data/lib/leftovers/merged_config.rb

@@ -12,6 +12,7 @@ module Leftovers
 
       self << :ruby
       self << project_config
+      self << project_todo
       load_bundled_gem_config
     end
 
@@ -32,6 +33,10 @@ module Leftovers
       Leftovers::Config.new(:'.leftovers.yml', path: Leftovers.pwd + '.leftovers.yml')
     end
 
+    def project_todo
+      Leftovers::Config.new(:'.leftovers_todo.yml', path: Leftovers.pwd + '.leftovers_todo.yml')
+    end
+
     def unmemoize
       remove_instance_variable(:@exclude_paths) if defined?(@exclude_paths)
       remove_instance_variable(:@include_paths) if defined?(@include_paths)

data/lib/leftovers/reporter.rb

@@ -2,10 +2,62 @@
 
 module Leftovers
   class Reporter
-    def call(definition)
-      Leftovers.puts(
-        "\e[36m#{definition.location_s}\e[0m #{definition} \e[2m#{definition.highlighted_source("\e[33m", "\e[0;2m")}\e[0m" # rubocop:disable Layout/LineLength
-      )
+    def prepare; end
+
+    def report(only_test:, none:)
+      report_list('Only directly called in tests:', only_test)
+      report_list('Not directly called at all:', none)
+      report_instructions
+
+      1
+    end
+
+    def report_success
+      puts green('Everything is used')
+
+      0
+    end
+
+    private
+
+    def report_instructions
+      puts <<~HELP
+
+        how to resolve: #{green Leftovers.resolution_instructions_link}
+      HELP
+    end
+
+    def report_list(title, list)
+      return if list.empty?
+
+      puts red(title)
+      list.each { |d| print_definition(d) }
+    end
+
+    def print_definition(definition)
+      puts "#{aqua definition.location_s} "\
+        "#{definition} "\
+        "#{grey definition.highlighted_source("\e[33m", "\e[0;2m")}"
+    end
+
+    def puts(string)
+      Leftovers.puts(string)
+    end
+
+    def red(string)
+      "\e[31m#{string}\e[0m"
+    end
+
+    def green(string)
+      "\e[32m#{string}\e[0m"
+    end
+
+    def aqua(string)
+      "\e[36m#{string}\e[0m"
+    end
+
+    def grey(string)
+      "\e[2m#{string}\e[0m"
     end
   end
 end

data/lib/leftovers/todo_reporter.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Leftovers
+  class TodoReporter
+    def prepare
+      return unless path.exist?
+
+      puts "Removing previous #{path.basename} file"
+      puts ''
+      path.delete
+    end
+
+    def report(only_test:, none:)
+      path.write(generate_file_body(only_test, none))
+      report_instructions
+
+      0
+    end
+
+    def report_success
+      puts "No #{path.basename} file generated, everything is used"
+
+      0
+    end
+
+    private
+
+    def report_instructions
+      puts <<~MESSAGE
+        generated #{path.basename}.
+        running leftovers again will read this file and
+        not alert you to any unused items mentioned in it.
+
+        commit this file so you/your team can gradually
+        address these items while still having leftovers
+        alert you to any newly unused items.
+      MESSAGE
+    end
+
+    def path
+      Leftovers.pwd.join('.leftovers_todo.yml')
+    end
+
+    def generate_file_body(only_test, none)
+      <<~YML.chomp
+        #{generation_message.chomp}
+        #
+        #{resolution_instructions}
+        #{todo_data(only_test, none).chomp}
+      YML
+    end
+
+    def generation_message
+      <<~YML
+        # This file was generated by `leftovers --write-todo`
+        # Generated at: #{Time.now.utc.strftime('%F %T')} UTC
+      YML
+    end
+
+    def resolution_instructions
+      <<~YML
+        # for instructions on how to address these
+        # see #{Leftovers.resolution_instructions_link}
+      YML
+    end
+
+    def todo_data(only_test, none)
+      none_test = none.select(&:test?)
+      none_non_test = none.reject(&:test?)
+      [
+        test_only_data(none_test),
+        keep_data(only_test, none_non_test)
+      ].compact.join
+    end
+
+    def test_only_data(list)
+      return if list.empty?
+
+      <<~YML
+        test_only:
+        #{generate_list('Defined in tests:', list).chomp}
+      YML
+    end
+
+    def keep_data(only_test, none_non_test)
+      return if only_test.empty? && none_non_test.empty?
+
+      <<~YML.chomp
+        keep:
+        #{keep_test_called_data(only_test)}#{keep_never_called_data(none_non_test)}
+      YML
+    end
+
+    def keep_test_called_data(list)
+      return if list.empty?
+
+      generate_list('Only directly called in tests:', list)
+    end
+
+    def keep_never_called_data(list)
+      return if list.empty?
+
+      generate_list('Not directly called at all:', list)
+    end
+
+    def generate_list(title, list)
+      <<~YML
+          # #{title}
+        #{list.map { |d| print_definition(d) }.join("\n")}
+
+      YML
+    end
+
+    def print_definition(definition)
+      "  - #{definition.to_s.inspect} # #{definition.location_s} #{definition.source_line.strip}"
+    end
+
+    def puts(string)
+      Leftovers.puts(string)
+    end
+  end
+end

data/lib/leftovers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leftovers
-  VERSION = '0.4.2'
+  VERSION = '0.4.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: leftovers
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Dana Sherson
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-20 00:00:00.000000000 Z
+date: 2021-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -178,6 +178,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: tty_string
   requirement: !ruby/object:Gem::Requirement
@@ -381,6 +395,7 @@ files:
 - lib/leftovers/processor_builders/value.rb
 - lib/leftovers/rake_task.rb
 - lib/leftovers/reporter.rb
+- lib/leftovers/todo_reporter.rb
 - lib/leftovers/value_processors.rb
 - lib/leftovers/value_processors/add_dynamic_prefix.rb
 - lib/leftovers/value_processors/add_dynamic_suffix.rb
@@ -439,7 +454,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Find unused methods and classes/modules