churn_vs_complexity 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2efc73253aa94e1fe4de49723e2d7238857aa1a1f0b37fa6c39cb3e6cd1a133a
-  data.tar.gz: '09be5e6af924ce5d32cc81e918f88e943f13e3c80e78bffaeb799c957d300c78'
+  metadata.gz: d748bfb7d21087a5fbcb360dbc05dcd46b5ec05bf2c2fcc542e2e25368084d78
+  data.tar.gz: 0d160c582aee2696823061dd7623cf17e9b537d798ae31502eb30b065a61391d
 SHA512:
-  metadata.gz: 72fb9a5556e813e7999ca5134e91566e9c2b64e9050076c170578db470cb98c68bd53c440fb2b15b68db60abddab9af40026723deb543cf44b6a83acaeeed83e
-  data.tar.gz: 17adf306ab68cf12ed73b733f2810df28761f726077cd6825ddb393fa89cf1fa264c66fd98eccd8c7bdfafb24af953e04f8b05a276615a2c0ae8b6c59be1c02b
+  metadata.gz: f521d39fddad8e8adf05ab0f21d8b8adcc2460f9a57c553b90c73eb60451aafed19ab11977768d494987ff72838c856dd04c3910781ec0da34f53d82d18d9d4e
+  data.tar.gz: 3ab17db013540128bd428edb54cf0615f47ce50caa19d1ad418261c20efde494bb36ea8e84408e0ca330f7721013a9e8958f3cd5a16565636186508e59bf7360

data/CHANGELOG.md

@@ -1,3 +1,14 @@
 ## [1.0.0] - 2024-06-07
 
-- Initial release
+- Initial release
+
+## [1.1.0] - 2024-09-20
+
+- Introduce `--summary` flag to output summary statistics for churn and complexity
+- Introduce `--month`, `--quarter`, and `--year` short-hand flags to calculate churn for different time periods relative to the most recent commit
+
+## [1.2.0] - 2024-09-20
+
+- Fix bug in CLI where new flags and `--since` would not be recognized
+- Improve selection of observations included in the output
+- Fixed calculation of churn that would never be zero

data/README.md

@@ -31,13 +31,17 @@ In order to use the `--java` flag, you must first install PMD manually, and the
 Execute the `churn_vs_complexity` with the applicable arguments. Output in the requested format will be directed to stdout.
 
 ```
-churn_vs_complexity [options] folder
+Usage: churn_vs_complexity [options] folder
         --java                       Check complexity of java classes
         --ruby                       Check complexity of ruby files
         --csv                        Format output as CSV
         --graph                      Format output as HTML page with Churn vs Complexity graph
+        --summary                    Output summary statistics (mean and median) for churn and complexity
         --excluded PATTERN           Exclude file paths including this string. Can be used multiple times.
         --since YYYY-MM-DD           Calculate churn after this date
+    -m, --month                      Calculate churn for the month leading up to the most recent commit
+    -q, --quarter                    Calculate churn for the quarter leading up to the most recent commit
+    -y, --year                       Calculate churn for the year leading up to the most recent commit
     -h, --help                       Display help
 ```
 
@@ -47,6 +51,7 @@ churn_vs_complexity [options] folder
 
 `churn_vs_complexity --java --graph --exclude generated-sources --exclude generated-test-sources --since 2023-01-01 my_java_project > ~/Desktop/java-demo.html`
 
+`churn_vs_complexity --ruby --summary -m my_ruby_project >> ~/Desktop/monthly-report.txt`
 
 
 ## Development

data/lib/churn_vs_complexity/churn.rb

@@ -7,20 +7,18 @@ module ChurnVsComplexity
     module GitCalculator
       class << self
         def calculate(folder:, file:, since:)
-          with_follow = calculate_with_follow(folder, file, since)
-          with_follow.zero? ? repo(folder).log.path(file).size : with_follow
+          git_dir = File.join(folder, '.git')
+          formatted_date = since.strftime('%Y-%m-%d')
+          cmd = %Q(git --git-dir #{git_dir} --work-tree #{folder} log --format="%H" --follow --since="#{formatted_date}" -- #{file} | wc -l)
+          `#{cmd}`.to_i
         end
 
-        private
-
-        def calculate_with_follow(folder, file, since)
-          # Format the date as "YYYY-MM-DD"
-          formatted_date = since.strftime('%Y-%m-%d')
-          # git log --follow --oneline --since="YYYY-MM-DD" <file_path> | wc -l
-          `git --git-dir #{File.join(folder,
-                                     '.git',)} --work-tree #{folder} log --follow --oneline --since=#{formatted_date} #{file} | wc -l`.to_i
+        def date_of_latest_commit(folder:)
+          repo(folder).log.first.date
         end
 
+        private
+
         def repo(folder)
           repos[folder] ||= Git.open(folder)
         end

data/lib/churn_vs_complexity/cli.rb

@@ -9,7 +9,6 @@ module ChurnVsComplexity
     def self.run!
       # Create an options hash to store parsed options
       options = { excluded: [] }
-      since = nil
 
       # Initialize OptionParser
       OptionParser.new do |opts|
@@ -31,13 +30,34 @@ module ChurnVsComplexity
           options[:serializer] = :graph
         end
 
+        opts.on('--summary', 'Output summary statistics (mean and median) for churn and complexity') do
+          options[:serializer] = :summary
+        end
+
         opts.on('--excluded PATTERN',
                 'Exclude file paths including this string. Can be used multiple times.',) do |value|
           options[:excluded] << value
         end
 
         opts.on('--since YYYY-MM-DD', 'Calculate churn after this date') do |value|
-          since = value
+          options[:since] = value
+        end
+
+        opts.on('-m', '--month', 'Calculate churn for the month leading up to the most recent commit') do
+          options[:since] = :month
+        end
+
+        opts.on('-q', '--quarter', 'Calculate churn for the quarter leading up to the most recent commit') do
+          options[:since] = :quarter
+        end
+
+        opts.on('-y', '--year', 'Calculate churn for the year leading up to the most recent commit') do
+          options[:since] = :year
+        end
+
+        opts.on('--dry-run', 'Echo the chosen options from the CLI') do
+          puts options
+          exit
         end
 
         opts.on('-h', '--help', 'Display help') do
@@ -56,24 +76,11 @@ module ChurnVsComplexity
 
       raise Error, 'No options selected. Use --help for usage information.' if options.empty?
 
-      begin
-        if since.nil?
-          since = Time.at(0).to_date
-          options[:graph_title] = 'Churn vs Complexity'
-        else
-          date_string = since
-          since = Date.strptime(since, '%Y-%m-%d')
-          options[:graph_title] = "Churn vs Complexity since #{date_string}"
-        end
-      rescue StandardError
-        raise Error, "Invalid date #{since}, please use correct format, YYYY-MM-DD"
-      end
-
       config = Config.new(**options)
 
       config.validate!
 
-      puts config.to_engine.check(folder:, since:)
+      puts config.to_engine.check(folder:)
     end
   end
 end

data/lib/churn_vs_complexity/concurrent_calculator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'etc'
+
 module ChurnVsComplexity
   class ConcurrentCalculator
     CONCURRENCY = Etc.nprocessors
@@ -11,7 +13,9 @@ module ChurnVsComplexity
     end
 
     def calculate(folder:, files:, since:)
-      schedule_churn_calculation(folder, files, since)
+      latest_commit_date = @churn.date_of_latest_commit(folder:)
+      @git_period = GitDate.git_period(since, latest_commit_date)
+      schedule_churn_calculation(folder, files[:included], @git_period.effective_start_date)
       calculate_complexity(folder, files)
       await_results
       combine_results
@@ -22,9 +26,11 @@ module ChurnVsComplexity
     def calculate_complexity(folder, files)
       @complexity_results =
         if @complexity.folder_based?
-          @complexity.calculate(folder:)
+          result = @complexity.calculate(folder:)
+          files[:explicitly_excluded].each { |file| result.delete(file) }
+          result
         else
-          files.each_with_object({}) do |file, acc|
+          files[:included].each_with_object({}) do |file, acc|
             acc.merge!(@complexity.calculate(file:))
           end
         end
@@ -51,10 +57,14 @@ module ChurnVsComplexity
     end
 
     def combine_results
-      @churn_results.to_h do |file, churn|
-        complexity = @complexity_results[file] || -1
-        [file, [churn, complexity]]
+      result = {}
+      result[:values_by_file] = @complexity_results.keys.each_with_object({}) do |file, acc|
+        # File with complexity score might not have churned in queried period, 
+        # set zero churn on miss
+        acc[file] = [@churn_results[file] || 0, @complexity_results[file]]
       end
+      result[:git_period] = @git_period
+      result
     end
   end
 end

data/lib/churn_vs_complexity/config.rb

@@ -6,21 +6,23 @@ module ChurnVsComplexity
       language:,
       serializer:,
       excluded: [],
-      graph_title: nil,
-      complexity_validator: ComplexityValidator
+      since: nil,
+      complexity_validator: ComplexityValidator,
+      since_validator: SinceValidator
     )
       @language = language
       @serializer = serializer
       @excluded = excluded
+      @since = since
       @complexity_validator = complexity_validator
-      @graph_title = graph_title
+      @since_validator = since_validator
     end
 
     def validate!
       raise Error, "Unsupported language: #{@language}" unless %i[java ruby].include?(@language)
-      raise Error, "Unsupported serializer: #{@serializer}" unless %i[none csv graph].include?(@serializer)
-      raise Error, 'Please provide a title for the graph' if @serializer == :graph && @graph_title.nil?
+      raise Error, "Unsupported serializer: #{@serializer}" unless %i[none csv graph summary].include?(@serializer)
 
+      @since_validator.validate!(@since)
       @complexity_validator.validate!(@language)
     end
 
@@ -32,6 +34,7 @@ module ChurnVsComplexity
           churn:,
           file_selector: FileSelector::Java.excluding(@excluded),
           serializer:,
+          since: @since,
         )
       when :ruby
         Engine.concurrent(
@@ -39,6 +42,7 @@ module ChurnVsComplexity
           churn:,
           file_selector: FileSelector::Ruby.excluding(@excluded),
           serializer:,
+          since: @since,
         )
       end
     end
@@ -54,7 +58,9 @@ module ChurnVsComplexity
       when :csv
         Serializer::CSV
       when :graph
-        Serializer::Graph.new(title: @graph_title)
+        Serializer::Graph.new
+      when :summary
+        Serializer::Summary
       end
     end
 
@@ -66,5 +72,24 @@ module ChurnVsComplexity
         end
       end
     end
+
+    module SinceValidator
+      def self.validate!(since)
+        # since can be nil, a date string or a keyword (:month, :quarter, :year)
+        return if since.nil?
+
+        if since.is_a?(Symbol)
+          raise Error, "Invalid since value #{since}" unless %i[month quarter year].include?(since)
+        elsif since.is_a?(String)
+          begin
+            Date.strptime(since, '%Y-%m-%d')
+          rescue StandardError
+            raise Error, "Invalid date #{since}, please use correct format, YYYY-MM-DD"
+          end
+        else
+          raise Error, "Invalid since value #{since}"
+        end
+      end
+    end
   end
 end

data/lib/churn_vs_complexity/engine.rb

@@ -2,20 +2,21 @@
 
 module ChurnVsComplexity
   class Engine
-    def initialize(file_selector:, calculator:, serializer:)
+    def initialize(file_selector:, calculator:, serializer:, since:)
       @file_selector = file_selector
       @calculator = calculator
       @serializer = serializer
+      @since = since
     end
 
-    def check(folder:, since:)
+    def check(folder:)
       files = @file_selector.select_files(folder)
-      result = @calculator.calculate(folder:, files:, since:)
+      result = @calculator.calculate(folder:, files:, since: @since)
       @serializer.serialize(result)
     end
 
-    def self.concurrent(complexity:, churn:, serializer: Serializer::None, file_selector: FileSelector::Any)
-      Engine.new(file_selector:, serializer:, calculator: ConcurrentCalculator.new(complexity:, churn:))
+    def self.concurrent(since:, complexity:, churn:, serializer: Serializer::None, file_selector: FileSelector::Any)
+      Engine.new(since:, file_selector:, serializer:, calculator: ConcurrentCalculator.new(complexity:, churn:))
     end
   end
 end

data/lib/churn_vs_complexity/file_selector.rb

@@ -4,7 +4,8 @@ module ChurnVsComplexity
   module FileSelector
     module Any
       def self.select_files(folder)
-        Dir.glob("#{folder}/**/*").select { |f| File.file?(f) }
+        included = Dir.glob("#{folder}/**/*").select { |f| File.file?(f) }
+        { explicitly_excluded: [], included: }
       end
     end
 
@@ -15,9 +16,16 @@ module ChurnVsComplexity
       end
 
       def select_files(folder)
-        Dir.glob("#{folder}/**/*").select do |f|
-          !has_excluded_pattern?(f) && has_correct_extension?(f) && File.file?(f)
+        were_excluded = []
+        were_included = []
+        Dir.glob("#{folder}/**/*").each do |f|
+          if has_excluded_pattern?(f)
+            were_excluded << f
+          elsif has_correct_extension?(f) && File.file?(f)
+            were_included << f
+          end
         end
+        { explicitly_excluded: were_excluded, included: were_included }
       end
 
       private

data/lib/churn_vs_complexity/git_date.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ChurnVsComplexity
+  module GitDate
+    def self.git_period(cli_arg_since, latest_commit_date)
+      latest_commit_date = latest_commit_date.to_date
+      if cli_arg_since.nil?
+        NoStartGitPeriod.new(latest_commit_date)
+      elsif cli_arg_since.is_a?(Symbol)
+        AbsoluteGitPeriod.looking_back(relative_period: cli_arg_since, from: latest_commit_date)
+      elsif cli_arg_since.is_a?(String)
+        AbsoluteGitPeriod.between(cli_arg_since, latest_commit_date)
+      else
+        raise Error, "Unexpected since value #{cli_arg_since}"
+      end
+    end
+
+    class NoStartGitPeriod
+      attr_reader :end_date
+
+      def initialize(end_date)
+        @end_date = end_date
+      end
+
+      def effective_start_date = Time.at(0)
+
+      def requested_start_date = nil
+    end
+
+    class AbsoluteGitPeriod
+      attr_reader :end_date
+
+      def self.between(cli_arg_since, latest_commit_date)
+        start_date = Date.strptime(cli_arg_since, '%Y-%m-%d')
+        new(start_date, latest_commit_date)
+      end
+
+      def self.looking_back(relative_period:, from:)
+        shifter = case relative_period
+                  when :month then 1
+                  when :quarter then 3
+                  when :year then 12
+                  else raise Error, "Unexpected since value #{relative_period}"
+                  end
+        start_date = from << shifter
+        new(start_date, from)
+      end
+
+      def initialize(start_date, end_date)
+        @start_date = start_date
+        @end_date = end_date
+      end
+
+      def effective_start_date = @start_date
+
+      def requested_start_date = @start_date
+    end
+  end
+end

data/lib/churn_vs_complexity/serializer.rb

@@ -2,12 +2,55 @@
 
 module ChurnVsComplexity
   module Serializer
+    def self.title(result)
+      requested_start_date = result[:git_period].requested_start_date
+      end_date = result[:git_period].end_date
+      if requested_start_date.nil?
+        "Churn until #{end_date.strftime('%Y-%m-%d')} vs complexity"
+      else
+        "Churn between #{requested_start_date.strftime('%Y-%m-%d')} and #{end_date.strftime('%Y-%m-%d')} vs complexity"
+      end
+    end
+
     module None
-      def self.serialize(values_by_file) = values_by_file
+      def self.serialize(result) = result
+    end
+
+    module Summary
+      def self.serialize(result)
+        values_by_file = result[:values_by_file]
+        churn_values = values_by_file.map { |_, values| values[0].to_f }
+        complexity_values = values_by_file.map { |_, values| values[1].to_f }
+
+        mean_churn = churn_values.sum / churn_values.size
+        median_churn = churn_values.sort[churn_values.size / 2]
+        mean_complexity = complexity_values.sum / complexity_values.size
+        median_complexity = complexity_values.sort[complexity_values.size / 2]
+
+        product = values_by_file.map { |_, values| values[0].to_f * values[1].to_f }
+        mean_product = product.sum / product.size
+        median_product = product.sort[product.size / 2]
+
+        <<~SUMMARY
+          #{Serializer.title(result)}
+
+          Number of observations: #{values_by_file.size}
+
+          Churn:
+          Mean #{mean_churn}, Median #{median_churn}
+
+          Complexity:
+          Mean #{mean_complexity}, Median #{median_complexity}
+
+          Product of churn and complexity:
+          Mean #{mean_product}, Median #{median_product}
+        SUMMARY
+      end
     end
 
     module CSV
-      def self.serialize(values_by_file)
+      def self.serialize(result)
+        values_by_file = result[:values_by_file]
         values_by_file.map do |file, values|
           "#{file},#{values[0]},#{values[1]}\n"
         end.join
@@ -15,16 +58,16 @@ module ChurnVsComplexity
     end
 
     class Graph
-      def initialize(title:, template: Graph.load_template_file)
+      def initialize(template: Graph.load_template_file)
         @template = template
-        @title = title
       end
 
-      def serialize(values_by_file)
-        data = values_by_file.map do |file, values|
+      def serialize(result)
+        data = result[:values_by_file].map do |file, values|
           "{ file_path: '#{file}', churn: #{values[0]}, complexity: #{values[1]} }"
         end.join(",\n") + "\n"
-        @template.gsub("// INSERT DATA\n", data).gsub('INSERT TITLE', @title)
+        title = Serializer.title(result)
+        @template.gsub("// INSERT DATA\n", data).gsub('INSERT TITLE', title)
       end
 
       def self.load_template_file

data/lib/churn_vs_complexity/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChurnVsComplexity
-  VERSION = '1.0.0'
+  VERSION = '1.2.0'
 end

data/lib/churn_vs_complexity.rb

@@ -12,6 +12,7 @@ require_relative 'churn_vs_complexity/churn'
 require_relative 'churn_vs_complexity/cli'
 require_relative 'churn_vs_complexity/config'
 require_relative 'churn_vs_complexity/serializer'
+require_relative 'churn_vs_complexity/git_date'
 
 module ChurnVsComplexity
   class Error < StandardError; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: churn_vs_complexity
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Erik T. Madsen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-07 00:00:00.000000000 Z
+date: 2024-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: flog
@@ -68,6 +68,7 @@ files:
 - lib/churn_vs_complexity/config.rb
 - lib/churn_vs_complexity/engine.rb
 - lib/churn_vs_complexity/file_selector.rb
+- lib/churn_vs_complexity/git_date.rb
 - lib/churn_vs_complexity/serializer.rb
 - lib/churn_vs_complexity/version.rb
 - tmp/pmd-support/ruleset.xml
@@ -89,7 +90,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/beatmadsen/churn_vs_complexity
-  changelog_uri: https://github.com/beatmadsen/churn_vs_complexity/CHANGELOG.md
+  changelog_uri: https://github.com/beatmadsen/churn_vs_complexity/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []